Falls Du von Salesforce Commerce Cloud zu Klaviyo migrieren möchtest, zeigt Dir dieser Guide, der auf dem entsprechenden Guide im (englischsprachigen) Help-Center von Klaviyo basiert, die nötigen Schritte.

Die Cartridge- und API-Integration von Klaviyo ermöglicht es Websites, die Salesforce Commerce Cloud (ehemals Demandware) nutzen, sich schnell zu integrieren und sowohl Echtzeit- als auch historische Daten an Klaviyo zu übertragen. Eine Cartridge ist ein Erweiterungsmodul. Wenn die Salesforce Commerce Cloud (SFCC) integriert ist, beginnt Klaviyo mit dem Tracking von Aktionen in Echtzeit, wie z.B. Website-Navigation, Tracking von Suchen, Anzeige von Produkten, Anzeige von Kategorien, Hinzufügen von Artikeln zu einem Warenkorb, Checkout und Bestellung.

Die Integration der Salesforce Commerce Cloud (SFCC) mit Klaviyo erfolgt in drei Schritten. Dieser Guide behandelt diese Schritte und die damit verbundenen Aufgaben zur Integration von SFCC-Stores:

  1. Installation von Klaviyo Cartridge in SFCC.
  2. Hinzufügen von Enablement-Snippets zu SFCC.
  3. Aktivierung der SFCC OCAPI-Integration in Klaviyo.

Klaviyo lässt sich sowohl mit der SFCC-Controller-basierten Site Genesis (SG), als auch mit der Storefront Reference Architecture Site Genesis (SFRA) integrieren. Jedes Framework erfordert ein etwas anderes Cartridge-Setup und Snippets, die im Folgenden beschrieben werden.

Wenn Du zunächst Deine Entwicklungsumgebung integrieren möchtest, kannst Du mit der hier beschriebenen Methode einen verknüpften Klaviyo-Account erstellen und Deine Entwicklungsumgebung mit diesem Konto verknüpfen. Es wird empfohlen, das Wort "Dev" oder "Staging" in den Firmennamen aufzunehmen, den Du beim Einrichten des Accounts verwendest, um die Accounts beim Einloggen besser unterscheiden zu können. 

Erweiterungs-Module Setup

Das Klaviyo Cartridge-Setup besteht aufgrund der unterschiedlichen Infrastrukturen von SFCC aus drei Haupt-Cartridges. Diese Cartridges beinhalten:

- int_klaviyo: für SiteGenesis-basierte Websites

- int_klaviyo_sfra: für SFRA-basierte Websites

- int_klaviyo_core: für beide Arten von Infrastrukturen, die einige grundlegende, sich überschneidende Funktionen enthalten

Du musst nur zwei der drei mitgelieferten Cartridges verwenden, int_klaviyo_core und die für das Framework Deiner SFCC-Website spezifische Cartridge. Sowohl Deine relevante Cartridge als auch die Core-Cartridge sind erforderlich, damit die Integration korrekt funktioniert.

Du findest die Cartridges in einem Zip-Archiv, das auf der Commerce Cloud XChange zum Download bereitsteht.

Import von Cartridges

Der erste Schritt besteht darin, die Cartridges in Eclipse zu importieren, damit sie für die Verknüpfung mit Deiner SFCC-Instanz verfügbar sind:

  1. Gehe in Eclipse zu Administration ImportGeneral Existing Projects into Workspace.
  2. Importiere das Verzeichnis int_klaviyo_core mit Hilfe des Import-Assistenten.
  3. Wähle die SFCC-Instanz aus, mit der die Cartridge verbunden werden soll.
  4. Wähle Properties ("Eigenschaften").
  5. Wähle Project References ("Projektreferenzen").
  6. Checke die Cartridge int_klaviyo_core ein.
  7. Wiederhole die Schritte 2 bis 6 für die andere Cartridge, die für Dein Framework spezifisch ist (entweder int_klaviyo oder int_klaviyo_sfra).

Hinzufügen von Cartridges zum Cartridge-Pfad

Sobald die Cartridges importiert worden sind, müssen sie mit dem Business Manager von SFCC in die Liste der von Deinem Standort verwendeten Cartridges hinzugefügt werden.

  1. Gehe zu Administration Sites Manage Sites
  2. Wähle Deinen Standort aus.
  3. Wähle Settings ("Einstellungen")
  4. Füge am Ende der mit Cartridges genannten Pfad-Eingabe die Namen der importierten Klaviyo-Cartridges mit der Core-Cartridge an letzter Stelle ein (entweder int_klaviyo:int_klaviyo_core oder int_klaviyo_sfra:int_klaviyo_core).
  5. Klicke auf Apply.

Nachdem Du auf Apply geklickt hast, solltest Du nun die beiden Cartridges am Ende des Feldes mit der Bezeichnung Effective Cartridge Path sehen.

Services hinzufügen

Nach dem Import der Cartridges und dem Hinzufügen zum Pfad der Site-Cartridges muss der Klaviyo-Service hinzugefügt werden, um die Konfiguration der Einstellungen für die Cartridge zu ermöglichen. Im Stammverzeichnis der Klaviyo-Cartridges-Zip-Datei befindet sich eine weitere Zip-Datei namens metadata.zip. Die folgenden Anweisungen beziehen sich auf diese Zip-Datei:

  1. Gehe zu Administration Site Development Site Import & Export Services.
  2. Lade die Datei metadata.zip hoch. Klaviyo Salesforce
  3. Wenn Du aufgefordert wirst zu bestätigen, ob Du das ausgewählte Archiv importieren möchtest, klicke auf OK

Du solltest nun den laufenden Import unter Status am unteren Rand der Seite sehen: Klaviyo Salesforce

Du hast nun Zugriff auf eine Einstellungsseite unter Merchant tools Site Preferences Custom Preferences klaviyoKlaviyo Salesforce

Hier kannst Du folgende Einstellungen verwalten:

- Klaviyo Enabled: Muss auf "Ja" gesetzt werden, um die Cartridge zu aktivieren

- Klaviyo Private Key: Dein privater Klaviyo API-Key

- Klaviyo Account: Dein(e) öffentliche(r) Klaviyo API-Key/Account-ID

- Image Type: Der Produktbildtyp, der in den an Klaviyo gesendeten Ereignisdaten verwendet werden soll

Wenn Du Dir nicht sicher bist, welchen Bildtyp Du einstellen sollst, gehe wie folgt vor: Merchant Tools   Products and Catalogs Products, klicke anschließend auf ein Produkt und lege anhand der verfügbaren Bilder fest, welchen Ansichtstyp Du verwenden möchtest (z.B. groß, mittel, klein, hochauflösend). Klaviyo Salesforce

Die Datei metadata.zip erstellt auch einen neuen Dienst in SFCC. Wenn Du zu Administration Operations Services gehst, sollte nun jeweils ein neuer Eintrag unter den Tabs zu sehen sein:

- Services ("KlaviyoTrackService") Klaviyo Salesforce

- Profiles ("KlaviyoTrackProfile") Klaviyo Salesforce

- Credentials ("KlaviyoTrackCredentials") Klaviyo Salesforce

Snippets hinzufügen

Der letzte Schritt des Cartridge-Setups besteht darin, einige Snippets zu Website-Template-Dateien hinzuzufügen, damit die Cartridge mit der Website kommunizieren kann. Diese Schritte unterscheiden sich jeweils geringfügig für die Architekturen Site Genesis (SG) und Storefront Reference Architecture (SFRA). Insofern solltest Du genau auf die Schritte achten.

Site Genesis (SG)

  1. Füge den folgenden Code am Ende der Datei footer_UI.isml ein:

<isinclude template="klaviyo/klaviyoFooter"/>

  1. Füge nun den folgenden Code in die minicart.isml, cart.isml und alle anderen "cart"-Isml-Dateien ein, die die Site verwendet:

<isif condition="${pdict.CurrentHttpParameterMap.cartAction == 'add' || pdict.CurrentHttpParameterMap.cartAction == 'update'}">

  <isinclude url="${URLUtils.url('Klaviyo-RenderKlaviyoAddToCart')}"/>

</isif>

Storefront Reference Architecture

  1. Füge den folgenden Code am Ende der Datei footer_UI.isml ein:

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

  1. Füge nun den folgenden Code zur AddProduct-Funktion in der Controller-Datei Cart.js hinzu, direkt vor der Zeile mit res.json({...});:

if(dw.system.Site.getCurrent().getCustomPreferenceValue('klaviyo_enabled')){

  var KlaviyoUtils = require('*/cartridge/scripts/utils/klaviyo/KlaviyoUtils');

  KlaviyoUtils.trackAddToCart();

Aktivierung der OCAPI-Integration

Endpoints

Um die Integration mit SFCC für Daten von Produktkatalogen oder historischen/laufenden Bestellungen zu ermöglichen, nutzt Klaviyo drei OCAPI Endpoints:

- /order_search: Synchronisiert historische Bestelldaten mit Klaviyo und darüber hinaus weiterhin alle 30 Minuten laufende Bestellereignisse. Die Ereignisse Ordered Product ("Bestelltes Produkt") und  Placed Order ("Platzierte Bestellung") synchronisieren zusätzliche Daten für die Segmentierung und und Filterung von Flows. Sie sind daher ideal für eine erweiterte Personalisierung, die nicht über das Ereignis Order Confirmation ("Bestellbestätigung") verfügbar ist. Verwende für Bestellbestätigungs-E-Mails in Echtzeit das Ereignis "Order Confirmation" aus der Cartridge.

- /sites: Ermöglicht es  auszuwählen, von welcher Seite Klaviyo während des Integration-Setups Daten synchronisiert.

- /product_search: Verknüpft Deinen Katalog mit Klaviyo, um Funktionen/Features wie z.B. Produktempfehlungsblöcke in E-Mails zu aktivieren.

Falls Dein Produktkatalog mehr als 10.000 Artikel umfasst, informiere bitte den Klavio-Kundensupport, bevor Du Deinen Katalog integrierst. Denn die OCAPIs haben Grenzen, sodass Du möglicherweise eine Einstellung auf Konfigurationsebene benötigst, um die Synchronisierungsrate zu begrenzen. Falls Du Deine OCAPI nicht auf die Version 18.3 aktualisieren kannst, setze Dich auch in diesem Falle mit dem Kundensupport in Verbindung.

SFCC-seitiges Setup

Bevor Klaviyo mit der OCAPI von SFCC kommunizieren kann, müssen einige Prämissen und Einstellungen in SFCC eingerichtet werden.

  1. Fügen einen API-Client für Klaviyo hinzu. Die API-Client-ID und das Passwort werden benötigt, um das Bearer-Token für OCAPI zu generieren.
  1. Sobald der API-Client hinzugefügt ist, gehe zu Administration Site Development Open Commerce API Settings im SFCC Business Manager.
  1. Füge die folgenden Snippets hinzu und ersetze dabei die API-Version und die Client-ID. Klaviyo unterstützt die API-Versionen 19.5 und höher sowie 18.8. Ersetze die CLIENT_ID durch jene API-Client-ID, die aus dem API-Client-Setup im vorherigen Schritt generiert wurde (diese sollte etwa so aussehen: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"). Wenn die Einstellungen für diese APIs bereits vorhanden sind, musst Du möglicherweise nur die hervorgehobenen Abschnitte unten zum bestehenden JSON-Array der Clients hinzufügen.

3.1: Füge das folgende JSON unter dem Typ Shop und dem Kontext Global (Organization Wide) hinzu, wobei Du SHOP_API_VERSION durch Deine OCAPI-Shop-API-Version ersetzt. Klicke dann auf Save.

{

         "_v":"SHOP_API_VERSION",

         "clients":[

            {

             "client_id":"CLIENT_ID",

             "resources":[

              {

               "resource_id":"/order_search",

               "methods":["post"],

               "read_attributes":"(**)",

               "write_attributes":"(**)"

              }

             ]

            }

         ]

        }

Nach dem Hinzufügen sollten die Einstellungen in etwa so aussehen: Klaviyo Salesforce

3.2: Füge das folgende JSON unter dem Typ data und dem Kontext Global (Organization Wide) hinzu, wobei Du DATA_API_VERSION durch Deine OCAPI Data API-Version ersetzt. Klicke dann auf Save.

{

     "_v":"DATA_API_VERSION",

     "clients":[

        {

         "client_id":"CLIENT_ID",

         "resources":[

          {

           "resource_id":"/product_search",

           "methods":["post"],

           "read_attributes":"(**)",

           "write_attributes":"(**)"

          },

          {

           "resource_id":"/sites",

           "methods":["get"],

           "read_attributes":"(**)",

           "write_attributes":"(**)"

          }

         ]

        }

     ]

    }

Die Einstellungen sollten anschließend in etwa so aussehen: Klaviyo Salesforce

Klaviyo-seitiges Setup

Gehe auf die SFCC-Integrations-Page in Deinem Account und füge die folgenden Daten hinzu:

- Store-URL: Deine Website-Domäne (z. B. example.com oder dev03-na01-example.demandware.net)

- Auth-Token: Erstellen Sie ein Auth-Token für diese Integration, das zum Anfordern eines Bearer-Tokens verwendet wird. Das Auth-Token wird durch Base-64-Kodierung der Client-ID und eines Passworts, verbunden durch einen Doppelpunkt (:), erzeugt (z. B. xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx:password).

- Data API Version: Die Version Deiner Daten-API, für die Du während des SFCC-seitigen Setups den Zugriff hinzugefügt hast (z. B. v19_10)

- Shop API Version: Die Version Deiner Shop-API, für die Du während des SFCC-seitigen Setups Zugriff hinzugefügt hast (z. B. v19_10)

- Katalog-ID: Die ID des SFCC-Katalogs, der mit Klaviyo synchronisiert werden soll (z. B. * oder etwas spezifischer wie storefront-catalog-de)

Nachdem Du diese Anmeldedaten eingegeben hast, klicke auf den Link Click here to retrieve the list of sites, um eine Liste der Sites auf Deiner SFCC-Instanz abzurufen. Klaviyo Salesforce

Nachdem die Sites abgerufen wurden, wählen jene Site aus, die mit diesem Account verknüpft werden soll. Klicke anschließend auf Connect to Salesforce Commerce Cloud .

Die Integration sollte nun beginnen, Deine Bestell-, Katalog- und Kundendaten zu synchronisieren.

Teste Deine SFCC-Integration

Um Dein Cartridge-Setup zu testen, gehen auf Deine Website und folgen diesen Anweisungen:

  1. Setze selbst ein Cookie, indem Du den url-Parameter utm_email als Deine E-Mail-Adresse in Deine Adressleiste einfügst, z.B.: _TEMP0_@email.com
  2. Durchsuche Deinen Katalog
  3. Zeige eine Kategorieseite an
  4. Zeige eine Produktseite an
  5. Lege einen Artikel in den Warenkorb
  6. Gib eine Testbestellung auf
  7. Gehe zum Activity-Feed Deines Klaviyo Dashboards oder zum Profil der E-Mail, die Du für den Cookie verwendet hast. Du solltest sehen, dass Deine Aktionen als Ereignisse (Events)erscheinen.

Überprüfen und Verstehen Deiner Salesforce Commerce Cloud-Daten

Die Salesforce Commerce Cloud-Integration ermöglicht das Tracking der folgenden Datenpunkte:

- Searched Site (Gesuchte Seite): Ereignis, das ausgelöst wird, wenn jemand eine Suche initiiert. 

- Viewed Product (Angesehenes Produkt): Ereignis, das ausgelöst wird, wenn sich jemand eine Produktseite ansieht.

- Viewed Category (Aufgerufene Kategorie): Ereignis, das ausgelöst wird, wenn jemand eine Kategorieseite aufruft.

- Added to Cart (zum Warenkorb hinzugefügt): Ereignis, das ausgelöst wird, wenn jemand etwas in den Warenkorb hinzufügt oder ihn verändert.

- Placed Order (Bestellung aufgegeben): Ereignis, das ausgelöst wird, wenn jemand eine Bestellung aufgibt (ganzheitliche Bestelldaten).

- Ordered Product (Bestelltes Produkt): Ereignis(e), das/die ausgelöst wird/werden, wenn jemand eine Bestellung aufgibt (spezifische Produktdaten).

-Order Confirmation (Bestellbestätigung): Ähnlich wie Placed Order, wird aber im Frontend ausgelöst, sobald der Checkout abgeschlossen ist.

- Started Checkout (Gestarteter Checkout): Ereignis, das ausgelöst wird, wenn jemand den Checkout-Prozess beginnt.

Du hast Fragen? Wir helfen Dir gerne!

Falls Du Fragen haben solltest oder Hilfe benötigst, melde Dich gerne jederzeit bei uns. Wir von Tante-E sind eine der führenden Shopify-Experten-Agenturen und einer der wenigen Klaviyo-Partner in Deutschland mit Standorten in Berlin und Köln. Wir betreiben eigene Onlineshops auf Shopify und haben darüber hinaus zahlreiche Projekte realisiert, sodass wir im Bereich E-Commerce im Allgemeinen und mit der Shopify-Plattform im Besonderen eine hohe Expertise besitzen. Falls Du also Fragen haben solltest, sind wir jederzeit für Dich da. Melde Dich einfach bei uns, wir freuen uns sehr auf Dich.

Shopify Klaviyo Partner

 

Bildquelle: Klaviyo

Zurück zum Blog