Grundlegendes zum Data-Warehouse-Ereignisimport in Klaviyo

Übersicht

Erfahre, wie du mit dem Data-Warehouse-Ereignisimport Ereignisdaten aus deinem Warehouse mit Klaviyo synchronisierst, damit du Segmente, Flows und Berichte mit Verhalten unterstützen kannst, das außerhalb der nativen Integrationen von Klaviyo entsteht (z. B. POS-Systeme, Supportplattformen oder benutzerdefinierte Anwendungen).

Was ist Data-Warehouse-Ereignisimport?

Mit dem Data-Warehouse-Ereignisimport kann Klaviyo eine direkte Verbindung zu deinem Data Warehouse herstellen und Importsynchronisierungen aus Warehouse-Tabellen oder -Sichten konfigurieren, die Ereignisdaten enthalten.

Jede Zeile in deiner Quelltabelle wird in Klaviyo als einzelnes Ereignis behandelt:

• Die Zeitstempel der Zeile, der Name der Metrik und die Kennungen definieren, was passiert ist, wann und für wen.
• Zusätzliche Spalten werden zu Ereigniseigenschaften, die du in Segmentierung, Flows und Auswertungen verwenden kannst.

Der Ereignisimport basiert auf derselben Data-Warehouse-Import-Infrastruktur wie der Profilimport, ist aber auf die Ereignisaufnahmepipeline von Klaviyo ausgerichtet und nicht auf Profile.

Wie funktioniert der Data-Warehouse-Ereignis-Import?

Nachdem du Klaviyo mit deinem Warehouse verbunden und eine Ereignissynchronisierung konfiguriert hast:

1. Klaviyo fragt dein Warehouse nach der konfigurierten Tabelle oder Ansicht ab.
2. Bei jeder Ausführung liest Klaviyo nur Zeilen, deren Zeitstempel für die Änderungserkennung neuer ist als die letzte erfolgreiche Synchronisierung. Dies ermöglicht inkrementelle Importe, ohne die gesamte Tabelle erneut zu verarbeiten.
3. Jede Zeile wird dann wie folgt verarbeitet:
   • Klaviyo bestimmt den Metriknamen (Ereignistyp) anhand der bei der Synchronisierungseinrichtung ausgewählten Optionen: entweder eine einzelne ausgewählte Metrik oder dynamisch anhand des Werts einer angegebenen Metriknamenspalte in der Quelltabelle.
   • Ereigniszeitstempel, Profilkennungen und optionale eindeutige ID, Wert und Wertwährung werden auf der Grundlage von Feldzuordnungen festgelegt, die während der Synchronisierungseinrichtung konfiguriert wurden.
   • Alle übrigen Spalten werden als Ereigniseigenschaften erfasst, wobei die Spaltennamen als Eigenschaftsnamen verwendet werden. Spaltennamen mit drei Unterstrichen (z. B. parent___child1, parent___child2) können verwendet werden, um eine Event-Eigenschaft (parent) mit untergeordneten Eigenschaften zu erstellen.
4. Klaviyo lädt die resultierenden Ereignisse in dein Konto und verhält sich dort wie bei anderen benutzerdefinierten API-Metriken in Segmentierung, Flows und Auswertungen.

Importe werden in regelmäßigen Abständen (z. B. stündlich) ausgeführt, sodass neue oder aktualisierte Zeilen in deinem Warehouse regelmäßig in Events in Klaviyo umgewandelt werden.

Bevor du anfängst

Vergewissere dich, dass die folgenden Anforderungen erfüllt sind, bevor du eine Synchronisierung für den Ereignis-Import erstellst:

• Dein Konto hat Zugriff auf Advanced KDP und Data-Warehouse-Import.
• Du hast eine Data-Warehouse-Verbindung in Klaviyo erstellt und validiert. Weitere Informationen zum erforderlichen Dienstkonto und den erforderlichen Schemata findest du in den Artikeln zum Support Center für dein Data Warehouse.
• Deine Quelltabelle oder -ansicht enthält die erforderlichen Spalten unten.
• Du hast ausreichende Berechtigungen in deinem Warehouse, um die erforderlichen Tabellen/Ansichten dem Service-Benutzer von Klaviyo zur Verfügung zu stellen.

Quelltabellenstruktur für Ereignisse

Um sicherzustellen, dass deine Ereignisdaten korrekt importiert werden können, muss deine Quelltabelle oder -ansicht die erforderlichen Felder und die Struktur von Klaviyo erfüllen.

Pflichtfelder

Die folgenden Spalten sind in V1 des Data Warehouse-Ereignisimports erforderlich:

Optionale Felder

Diese Felder werden gegebenenfalls empfohlen, sind aber nicht unbedingt erforderlich:

Ereigniseigenschaften

Alle anderen Spalten in deiner Tabelle werden als Ereigniseigenschaften behandelt:

• Spalten werden als verflachte Eigenschaften importiert, wobei der Spaltenname in Klaviyo direkt als Name der Eigenschaft verwendet wird.
• Du musst nicht jede Eigenschaft explizit zuordnen. Nicht zugeordnete Spalten werden als Ereigniseigenschaften einbezogen.
• Geschachtelte JSON-Elemente können bei Bedarf in einem einzelnen Eigenschaftswert gespeichert werden (z. B. ein JSON-Objekt von Zeilenelementen), aber der Eigenschaftsname selbst stammt aus einer Spalte der obersten Ebene.

Klaviyo führt für Ereigniseigenschaften eine Best-Effort-Typanalyse durch und stellt keine feldspezifische Transformationslogik als Teil der Einrichtung des Ereignisimports bereit.

Häufige Anwendungsfälle

Kund*innen verwenden den Data-Warehouse-Ereignis-Import in der Regel für:

1) Offline- oder POS-Ereignisse importieren

Binde In-Store- oder Offline-Events (z. B. POS-Käufe, Retouren oder Termine) aus deinem Warehouse ein, damit sie sich wie andere Klaviyo-Events und -Metriken verhalten.

Beispiele:

• In-Store Purchase Ereignisse mit Bestellsummen, Filialstandort und Zahlungsart
• Appointment Completed Events mit Mitarbeiter*in, Serviceart und Dauer

2) Service- und Support-Interaktionen

Synchronisiere Support- und Service-Ereignisse wie die Erstellung, Lösung oder Rückgabe von Tickets, um die Timelines deiner Kund*innen zu erweitern und Nachrichten basierend auf der Servicehistorie zu versenden.

Beispiele:

• Support Ticket Created und Support Ticket Resolved
• Order Returned mit Grundcodes und Erstattungsbeträgen

3) Modellierte oder abgeleitete Ereignisse

Wandle lagerortmodelliertes Verhalten in Ereignisse um, die in Klaviyo einfacher zu verwenden sind.

Beispiele:

• High Churn Risk Ereignisse, die von einem Modell in deinem Warehouse generiert werden
• Lifecycle Milestone Reached Ereignisse, wenn Kund*innen in einem benutzerdefinierten Lifecycle-Modell die Stufe wechseln

Richte eine Synchronisierung für den Data-Warehouse-Ereignis-Import ein

1) Verbinde dein Data Warehouse

Wenn du dein Warehouse noch nicht verbunden hast:

1. Gehe in Klaviyo zu Advanced KDP > Datenverwaltung > Synchronisierung.
2. Klicke auf Data Warehouse hinzufügen und wähle deinen Warehouse-Connector aus.
3. Führe die Verbindungsschritte für deine Plattform anhand der jeweiligen Verbindungsanleitung durch, die im Artikel zur Data-Warehouse-Import-Übersicht verlinkt ist.

Klaviyo unterstützt eine aktive Data-Warehouse-Verbindung pro Konto.

2) Neue Synchronisierung für den Ereignis-Import erstellen

Sobald dein Warehouse verbunden ist:

1. Wähle unter Advanced KDP > Datenverwaltung > Synchronisierung deine Warehouse-Verbindung aus.
2. Wähle Daten importieren (wenn du zum ersten Mal Importe konfigurierst) oder klicke für eine bestehende Verbindung auf Synchronisierung erstellen / Synchronisierung hinzufügen.
3. Wenn du zur Eingabe des Datentyps aufgefordert wirst, wähle Ereignisse (statt Profile) aus.
4. Wähle die Tabelle oder Ansicht in deinem Warehouse aus, die die Ereignisse enthält, die du importieren möchtest.

3) Pflichtfelder zuordnen

Als Nächstes ordnest du die Spalten aus deiner Warehouse-Tabelle den erforderlichen Ereignisfeldern von Klaviyo zu.

Für die Konfiguration des Ereignisimports musst du Zuordnungen bereitstellen für:

• Ereigniszeitstempel
• Metrikname (entweder eine Konstante, die du in der Konfiguration auswählst, oder eine Spalte, die den Metriknamen pro Zeile enthält)
• Profilkennung (mindestens eine)
• Zeitstempel der Erkennung ändern

Du kannst auch empfohlene Felder zuordnen:

• Eindeutige ID
• Eintrag
• Wert: Währung

Alle verbleibenden Spalten, die du diesen Kernfeldern nicht explizit zuordnest, werden automatisch zu Ereigniseigenschaften.

Die Konfigurations-UI verhindert, dass du mehrere Spalten demselben übergeordneten Feld zuordnen kannst, und überprüft, ob alle erforderlichen Felder vorhanden sind, bevor du sie speichern kannst.

4) Synchronisierungsfrequenz und historischen Umfang auswählen

Wenn du deinen Ereignis-Import speicherst:

• Klaviyo plant wiederkehrende Synchronisierungen für einen regelmäßigen Rhythmus (normalerweise stündlich).
• Bei jedem Durchlauf werden nur Zeilen verarbeitet, deren Zeitstempel der Änderungserkennung neuer ist als der letzte erfolgreiche Durchlauf. Dadurch wird sichergestellt, dass die Importe inkrementell erfolgen.

Für die historische Nachfüllung kannst du entweder:

• Zeige deinen Ereignis-Import auf eine Tabelle oder Ansicht, die bereits alle relevanten historischen Ereignisse enthält, oder
• Beginne mit einer dedizierten historischen Tabelle und wechsle später zu einer auf Änderungsdaten gestützten Ansicht, um fortlaufende Updates zu erhalten.

So verhalten sich importierte Ereignisse in Klaviyo

Einmal importiert:

• Jede Zeile wird als Ereignis einer benutzerdefinierten API-Metrik in Klaviyo angezeigt.
• Der Name der Metrik, die du zugeordnet hast (oder als Konstante konfiguriert hast), bestimmt den Event-Typnamen, den du im Produkt siehst (zum Beispiel Placed Order).
• Alle Profilkennungen werden nach Möglichkeit in bestehende Profile aufgelöst. Andernfalls erstellt Klaviyo neue Profile mithilfe der angegebenen Kennungsfelder, ähnlich wie bei anderen Ereignisaufnahmepfaden.

Mit diesen Ereignissen kannst du:

• Erstelle Segmente basierend auf dem, was jemand getan hat, und filtere nach Ereigniseigenschaften.
• Flows auslösen und filtern
• Analysiere das Verhalten in Metriken und im Reporting zusammen mit Ereignissen aus anderen Quellen.

Einschränkungen und Best Practices

Beachte beim Importieren von Data-Warehouse-Ereignissen Folgendes:

• Die Version 1 des Ereignisimports konzentriert sich nur auf Ereignisdaten. Profileigenschaften sollten über Profilimport oder andere unterstützte Pfade aktualisiert werden.
• Der Zeitstempel der Änderungserkennung muss sich vom Ereigniszeitstempel unterscheiden. Wenn du für beide die gleiche Spalte verwendest, kannst du historische Ereignisse nach der ersten Synchronisierung nicht mehr sicher importieren.
• Um eine optimale Geschwindigkeit zu erzielen, setze das Feld zur Änderungserkennung auf den Zeitstempel, mit dem die neue Tabelle erstellt wird. Datensätze werden in Synchronisierungszyklen mit diesem Wert gebündelt, sodass die Zeit zum Importieren historischer Datensätze verkürzt werden kann, wenn alle historischen Datensätze einen Änderungserkennungs-Zeitstempel in einem engen Bereich haben (z. B. den Zeitstempel eines Auftrags, der die neue Tabelle erstellt).
• Wenn möglich, verwendest du eine stabile eindeutige ID pro Ereignis, um die Deduplizierung zu verbessern und das Downstream-Debugging zu vereinfachen.
• Wenn deine Tabelle mehrere Ereignistypen (Metriken) mit unterschiedlichen Spaltensätzen enthält, ist es im Allgemeinen in Ordnung, sie zusammenzuhalten: Spalten, die für bestimmte Zeilen NULL sind, werden für diese Ereignisse in Klaviyo einfach ignoriert.
• Für komplexe verschachtelte Objekte (z. B. Zeilenelement-Arrays) empfehlen wir, sie nach Möglichkeit in mehrere Spalten zu gliedern, insbesondere für Eigenschaften, die du voraussichtlich in Segmentierung oder Flows verwenden wirst.

```

• Behalte den Zeitstempel für die Änderungserkennung in der Nähe des aktuellen Datums bei. Klaviyo liest Daten in 1-Stunden-Fenstern und iteriert vom ältesten Zeitstempel der Änderungserkennung in deiner Tabelle vorwärts. Wenn eine Zeile einen Zeitstempel für die Änderungserkennung weit in der Vergangenheit hat (z. B. einen einzigen Datensatz aus dem Jahr 2023, wenn alle anderen neu sind), scannt Klaviyo jedes 1-Stunden-Zeitfenster ab diesem Datum in jedem Synchronisierungszyklus durch, was zu einer langsamen historischen Backfill-Synchronisierung führt.
• Überschreite nicht mehr als etwa 100.000 Zeilen in einem einzigen Zeitstempelfenster von 1 Stunde zur Änderungserkennung. Wenn zu viele Zeilen dasselbe Zeitfenster von einer Stunde verwenden, kann es sein, dass die Synchronisierungsabfrage das Zeitlimit überschreitet.

Empfohlene Einrichtung des Snowflake-Clustering-Schlüssels

Bei Snowflake-Tabellen hilft das Clustering in der Zeitstempelspalte der Änderungserkennung, dass Klaviyo-Abfragen unnötige Mikropartitionen überspringen, was sowohl die Synchronisierungszeit als auch die Snowflake-Berechnungskosten reduziert:

ALTER TABLE your_schema.your_table CLUSTER BY (your_change_timestamp_column);