Closed-Loop-Schnittstelle

Dieses Kapitel beschreibt die Closed-Loop-Schnittstelle, die zum bidirektionalen Datenaustausch zwischen Optimizely Campaign und externen Systemen dient. Mithilfe der Closed-Loop-Schnittstelle können Sie zum Beispiel personalisierte Newsletter von einem externen Kampagnen-Management-System aus automatisiert in Optimizely Campaign erstellen und versenden.

Einrichtung

Wenden Sie sich an die Kundenbetreuung, um die Closed-Loop-Schnittstelle einzurichten und Informationen zur Verwendung von nicht anonymisierten Aktionsdaten zu erhalten.

Funktionsweise

Die Closed-Loop-Schnittstelle besteht aus zwei Modulen: dem Importmodul und dem Response-Daten-Export.

Um Mailings automatisiert zu erstellen und zu versenden, müssen Sie vorab ein Ursprungs-Mailing in Optimizely Campaign anlegen und die Mailing-ID an Ihr externes System, zum Beispiel ein Kampagnen-Management-System (KMS), übermitteln. Im KMS selektieren Sie die Empfänger und stellen die Empfängerdaten bereit.

Das Importmodul überträgt die Empfängerdaten inklusive der ID des Ursprungs-Mailings an Optimizely Campaign. Nach dem Import erhalten Sie eine Statusbenachrichtigung. In Optimizely Campaign wird eine Kampagnenkopie mit den personalisierten Inhalten (zum Beispiel Produktempfehlungen) erstellt und der Mailing-Versand ausgelöst - entweder direkt, oder zu einem festgelegten Zeitpunkt. Optional können Sie das Mailing manuell nachsenden, wenn Empfänger zum Beispiel Soft-Bounces Soft-Bounces treten auf, wenn E-Mails aufgrund vorübergehender Probleme nicht zugestellt werden können. Dies kann z. B. der Fall sein, wenn der Posteingang eines Empfängers voll ist. Posteingänge, die Mails per Soft-Bounce ablehnen, können zu einem späteren Zeitpunkt wieder verfügbar sein. erzeugt haben.

Der Response-Daten-Export überträgt die Response-Daten (Öffnungen, Klicks, Rückläufer, Abbestellungen) des versendeten Mailings zurück an Ihr KMS. Anschließend können Sie die Response-Daten im KMS oder einem Drittsystem, zum Beispiel einem Datawarehouse, weiter verarbeiten.

Das Importmodul und der Response-Daten-Export funktionieren unabhängig voneinander und können auch separat eingerichtet werden.

Datenübertragung

Die Datenübertragung findet über einen SFTP-Server bei Optimizely statt. Empfängerdaten werden dorthin transferiert. Die Response-Daten stehen auf dem SFTP-Server zum Download bereit.

Für laufende Transfers ist ein temporärer Dateiname notwendig, damit keine unvollständigen Dateien eingelesen werden. Siehe Behandlung von Transferproblemen. Die Namenskonventionen für die Dateien sind nachfolgend beschrieben.

Empfängerdaten übertragen

Es können jederzeit Empfängerdaten an den Optimizely Campaign SFTP-Server übertragen werden.

Die übertragenden Dateien müssen folgendem Namensschema entsprechen:

YYYYMMDDHHMMSS_subscribers.csv

Die Empfängerdatei selbst ist eine CSV Steht für „Comma-Separated Values“. Eine Textdatei mit Tabellendaten, die durch Kommazeichen voneinander getrennt sind.-Datei mit folgenden Eigenschaften:

• Satz- und Feldlängen sind innerhalb der Limitierungen der Empfängerliste variabel.
• Als Trennzeichen wird ein Semikolon (;) verwendet.
• Für Zeilenumbrüche wird ein Linefeed verwendet.
• Für die Begrenzung von Feldern werden Anführungsstriche ("") verwendet. Anführungsstriche werden durch vorangestellte Anführungsstriche gekennzeichnet.
• Es sind keine Angaben zu Spalten und Feldlängen am Beginn enthalten.
• Nicht gefüllte Felder (NULL) werden auch im einzelnen Satz nicht aufgefüllt. Die Anzahl der Feldtrenner bleibt konstant.

Empfängerdaten werden automatisiert alle 10 Minuten verarbeitet. Auf dem SFTP-Server von Optimizely Campaign werden maximal die Datenlieferungen der letzten 30 Tage vorgehalten.

Personalisierung und Empfehlungen

Es können weitere Daten geliefert werden, um die erstellten Mailings mit personalisierten Inhalten anzureichern, beispielsweise Produktempfehlungen.

Die CSV-Datei mit den Empfängerdaten wird dazu um weitere Felder erweitert, die eine Produkt-ID enthalten. Die dieser Produkt-ID zugehörigen Daten (z. B. Bezeichnung, Beschreibung, Bild-URL) werden über eine Content-Schnittstelle aus dem CMS abgerufen oder mit einer zweiten CSV-Datei übermittelt. Im Mailing werden die Produkt-Informationen über Feldfunktionen und Platzhalter eingefügt. Die Zuordnung der Produkt-IDs erfolgt kundenseitig.

Mit einem Web-Analyseprogramm können Produktempfehlungen aus Post-Click-Daten generiert und ins Mailing übergeben werden. Jedem Produkt sind weitere Produktempfehlungen zugeordnet. Das Auslesen der Produktinformationen erfolgt wie oben beschrieben über eine spezielle Feldfunktion. In diesem Fall muss keine kundenseitige Zuordnung der empfohlenen Produkte vorgenommen werden, da das Web-Analyseprogramm die Zuordnung automatisch entsprechend der initialen Konfiguration vornimmt.

Ursprungs-Mailing und Mailing-Versand anlegen

Als Grundlage für die zu versendende Kampagne müssen Sie ein Ursprungs-Mailing in Smart Campaigns anlegen und die Mailing-ID an das externe System übermitteln. Als Empfängerliste für das Ursprungs-Mailing muss die sogenannte Master-Liste angegeben werden. In die Produktparagraphen des Mailings werden Platzhalter eingefügt, die auf ein bestimmtes Feld in der Empfängerliste referenzieren. Dadurch können Produkt- und weitere Daten später beim Versand individuell zugeordnet und in das Mailing eingefügt werden.

Um mehrere Newsletter zu verschicken beziehungsweise bei zeitlicher Überschneidung im Versand, müssen Sie mehrere Ursprungs-Mailings angelegen. Das Ursprungs-Mailing selbst wird nicht versendet und muss im Status Neu bzw. Aktivierung erforderlich verbleiben. Sie dürfen das Mailing nicht aktivieren, da sonst die Kopie nicht erzeugt werden kann. Wird der Versand gestartet, legt das System automatisch eine Kopie des Ursprungs-Mailings an, die versendet wird. Das Ursprungs-Mailing kann danach erneut für den Versand verwendet werden.

Versand auslösen

Das Auslösen des Versands erfolgt durch das Ablegen einer Datei mit Empfängerdaten auf dem designierten Verzeichnis des SFTP-Servers von Optimizely. Ein Cron-Job prüft alle zehn Minuten, ob in diesem Verzeichnis neue Dateien vorhanden sind. Ist dies der Fall, wird die Datei in die Empfängerliste des entsprechenden Mandanten importiert und über den Wert BROADMAIL_ID das Ursprungs-Mailing zugeordnet.

Inhalte können auf zwei verschiedene Arten in das Mailing eingefügt werden:

• Direkt aus der Datei. Die einzufügenden Inhalte werden zusammen mit den Empfängerdaten in einer CSV-Datei importiert. Diese Variante ist nur für Texte und Hyperlinks möglich.
• Referenzierte Inhalte. Bei dieser Variante werden Inhalte über URLs in der importierten CSV-Datei referenziert und beim Versand über die Content-Schnittstelle vom externen Server des Kunden abgerufen. Sie können alle Arten von Inhalten (Text, Bilder, Anhänge, Hyperlinks) in ein Mailing einfügen.

Der Versand des Mailings wird automatisch gestartet, sobald die Daten importiert wurden. Jedes versendete Mailing erhält eine einzigartige ID.

Sie können eine Test-E-Mail mit der Closed-Loop-Schnittstelle versenden, indem Sie statt der richtigen Empfängerdaten Testdaten auf dem Server abgelegen. Die CSV-Datei mit den Testdaten muss den gleichen Aufbau besitzen wie die spätere Datei mit den richtigen Empfängerdaten. Für jeden Testversand wird ein weiteres Mailing in Optimizely Campaign angelegt.

Sie können das Ursprungs-Mailing für den Versand verschiedener Newsletter anpassen. Ändern Sie das Ursprungs-Mailing nur, nachdem das vorherige Mailing erfolgreich versendet wurde. Beachten Sie außerdem, dass in der Empfängerdatei für den Versand die richtige Mailing-ID des Ursprungs-Mailings eingetragen sein muss.

Behandlung von Transferproblemen

Sollte die Verarbeitung einer Datei nicht möglich sein, dann wird eine E-Mail-Benachrichtigung an eine zu konfigurierende Adresse gesendet. Es wird eine Fehlerdatei erzeugt und die Verarbeitung der Dateien ausgesetzt. Dieses Verhalten können Sie im späteren Verlauf noch anpassen. Nach Abschluss der Integration auf dem System können Sie diese Einstellung auch abschalten.

Nach einem Fehler muss die Schnittstelle sachgemäß hochgefahren werden. Der Wiederanlauf erfolgt auf Basis der Fehlerdatei. Es gibt zwei Fälle:

• Import der Daten fehlgeschlagen
• Fehler beim Auslösen eines Mailings nach dem Import

Fehler beim Transfer von Empfängerdaten werden durch die Optimizely Kundenbetreuung behandelt, da hier manuelles Eingreifen notwendig ist.

Protokollierung und Versandstatus

Nach dem Empfängerdaten-Import wird der Verarbeitungsstatus per E-Mail verschickt und in eine Log-Datei geschrieben. Dies gewährleistet, dass alle Aktionen der Schnittstelle auf Seiten von Optimizely Campaign dokumentiert sind.

Struktur der Hauptempfängerliste

Spaltenname	Datentyp	Beispiel	Beschreibung
Email	Varchar(255)	[email protected]	E-Mail-Adresse des Empfängers
BROADMAIL_ID	Bigint/Long	44018617811	Mailing-ID in Optimizely Campaign (BROADMAIL_ID)
WELLE_ID	Bigint/Long	46623317811	Identifiziert die Selektion/Versandwelle zur eindeutigen Zuordnung von Benutzeraktionen. Dieser Parameter wird optional vom externen System beim Empfängerdaten-Import übergeben.
Anrede	Varchar(255)		Feld aus bestehender Empfängerliste
Vorname	Varchar(255)		Feld aus bestehender Empfängerliste
Nachname	Varchar(255)		Feld aus bestehender Empfängerliste

Spezifikation der Response-Daten

Response-Daten werden täglich aus den Log-Dateien generiert und stehen zu einem vereinbarten Zeitpunkt zum Download auf dem SFTP-Server in Optimizely Campaign bereit. Die Dateien enthalten die neuen Daten seit der letzten Lieferung. Auf dem SFTP-Server stehen die Dateien mit den Daten der Mailings, die in den letzten 30 Tagen gestartet wurden, zur Verfügung.

Die Response-Daten basieren auf acht CSV-Dateien. Grundsätzlich können die CSV-Dateien als Tabellen betrachtet werden. Die Response-Daten werden als String-Datentyp exportiert. Sie können numerische Werte wie die Mailing- und Mandanten-ID auch in den Long-Datentyp konvertieren. Nachfolgend finden Sie detaillierte Typinformationen für jede Datei.

Versendete Mailings

Die Datei YYYYMMDD_mailings.csv enthält alle Mailings, die im Referenzzeitraum versendet wurden.

Spaltenname	Beschreibung	Beispiel	Schlüssel
id (mailingId)	Mailing-ID	51106527229	Primärschlüssel
compoundMasterId	Kampagnen-ID in Smart Campaigns	71206365463
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
mailing.recipientLists	Empfängerlisten-ID	58243723257
started	Startzeitpunkt des Mailings	2022-01-01 12:07:55
finished	Endzeitpunkt des Mailings	2022-01-01 12:09:10

Versand-Log

Die Datei YYYYMMDD_mailingrecipients.csv enthält auf Benutzerebene die genauen Versanddetails. Das Versand-Log referenziert auf die Mailings in der Datei YYYYMMDD_mailings.csv.

Spaltenname	Beschreibung	Beispiel	Schlüssel
id (mailingToUserId)	Kodierte Zuordnung des Empfängers	25951836752	Primärschlüssel
mailingId	Mailing-ID	51106527229	Fremdschlüssel
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
userId	E-Mail-Adresse des Empfängers	[email protected]
created	Versandzeitpunkt	2022-01-01 12:07:55
sendingStatus	Versandstatus	sending - Mailing wird versendet sent - Mailing wurde versendet could_not_be_sent - Mailing konnte nicht versendet werden
deliveryStatus	Zustellungsstatus	OK - Mailing wurde zugestellt HARD - Hard-Bounce Hard-Bounces treten auf, wenn eine E-Mail aufgrund eines dauerhaften Fehlers nicht zugestellt werden kann (z.B. weil die E-Mail-Adresse nicht mehr existiert). SOFT - Soft-Bounce Soft-Bounces treten auf, wenn E-Mails aufgrund vorübergehender Probleme nicht zugestellt werden können. Dies kann z. B. der Fall sein, wenn der Posteingang eines Empfängers voll ist. Posteingänge, die Mails per Soft-Bounce ablehnen, können zu einem späteren Zeitpunkt wieder verfügbar sein.
response.category	Rückläuferkategorie	unknown - Der Empfänger hat auf das Mailing geantwortet bounce - Soft-Bounce temporary_bounce - Soft-Bounce fatal_bounce - Hard-Bounce autoresponder - Autoresponder

Links

Die Datei YYYYMMDD_links.csv enthält alle Links, die in den Mailings enthalten sind. Es können nur Daten für Links mit aktivem Tracking geliefert werden.

Spaltenname	Beschreibung	Beispiel	Schlüssel
id (linkId)	Link-ID	44018617936	Primärschlüssel
mailingId	Mailing-ID	51106527229	Fremdschlüssel
mailingToUserId	Kodierte Zuordnung des Empfängers	25951836752	Fremdschlüssel
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
name	Link-Name	Impressum
url	Link-Ziel (URL)	http://www.example.com

Klicks

Die Datei YYYYMMDD_clicks.csv enthält alle Klicks durch Benutzer auf Links innerhalb eines Mailings aus dem Referenzzeitraum. Die Klicks können über die Datensätze in der dazugehörigen Datei YYYYMMDD_links.csv aufgelöst werden.

Spaltenname	Beschreibung	Beispiel	Schlüssel
linkId	Link-ID	44018617936	Fremdschlüssel
mailingId	Mailing-ID	51106527229	Fremdschlüssel
mailingToUserId	Kodierte Zuordnung des Empfängers	25951836752	Fremdschlüssel
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
userId	E-Mail-Adresse des Empfängers	[email protected]
created	Klick-Zeitpunkt Ein Benutzer kann mehrfach innerhalb einer Sekunde klicken.	2022-01-01 12:07:55
click.browser	Web-Browser	Firefox 64.1
click.platform	Betriebssystem	Windows 10
click.device	Gerätetyp	Desktop

Öffnungen

Die Datei YYYYMMDD_opens.csv enthält alle Öffnungen durch Benutzer von Mailings aus dem Referenzzeitraum.

Spaltenname	Beschreibung	Beispiel	Schlüssel
linkId	Link-ID	44018617936	Fremdschlüssel
mailingId	Mailing-ID	51106527229	Fremdschlüssel
mailingToUserId	Kodierte Zuordnung des Empfängers	25951836752	Fremdschlüssel
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
userId	E-Mail-Adresse des Empfängers	[email protected]
created	Öffnungszeitpunkt Ein Benutzer kann ein Mailing mehrfach öffnen. Es werden dann mehrere Datensätze generiert.	2022-01-01 12:07:55
open.browser	Web-Browser	Firefox 64.1
open.platform	Betriebssystem	Windows 10
open.device	Gerätetyp	Desktop

Automatische Öffnungen

Die Datei YYYYMMDD_automated_opens.csv enthält alle automatischen Öffnungen aus dem Referenzzeitraum. Siehe Apple E-Mail-Datenschutz.

Spaltenname	Beschreibung	Beispiel	Schlüssel
mailingId	Mailing-ID	51106527229	Fremdschlüssel
mailingToUserId	Kodierte Zuordnung des Empfängers	25951836752	Fremdschlüssel
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
userId	E-Mail-Adresse des Empfängers	[email protected]
created	Öffnungszeitpunkt	2022-01-01 12:07:55
open.browser	Web-Browser	Apple Mail Privacy Protection
open.platform	Betriebssystem	unknown

Abbestellungen

Die Datei YYYYMMDD_unsubscribes.csv enthält alle Abbestellungen durch Benutzer von Mailings aus dem Referenzzeitraum.

Spaltenname	Beschreibung	Beispiel	Schlüssel
mailingId	Mailing-ID	51106527229	Fremdschlüssel
mailingToUserId	Kodierte Zuordnung des Empfängers	25951836752	Fremdschlüssel
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
userId	E-Mail-Adresse des Empfängers	[email protected]
created	Zeitpunkt der Abbestellung	2022-01-01 12:07:55

Rückläufer

Die Datei YYYYMMDD_responses.csv enthält alle Rückläufer durch Benutzer von Mailings aus dem Referenzzeitraum.

Spaltenname	Beschreibung	Beispiel	Schlüssel
mailingId	Mailing-ID	51106527229	Fremdschlüssel
mailingToUserId	Kodierte Zuordnung des Empfängers	25951836752	Fremdschlüssel
mailingGroupId	Mandanten-ID (BROADMAIL_ID)	44018617811
userId	E-Mail-Adresse des Empfängers	[email protected]
created	Zeitpunkt des Rückläufers	2022-01-01 12:07:55
category	Rückläuferkategorie	unknown - Der Empfänger hat auf das Mailing geantwortet bounce - Soft-Bounce temporary_bounce - Soft-Bounce fatal_bounce - Hard-Bounce autoresponder - Autoresponder