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.
Tip
Da es sich bei den Response-Daten um Aktionsdaten handelt, die nicht anonymisiert sind, müssen Sie Optimizely vorab von allen eventuell aus der Bereitstellung dieser Funktionalität resultierenden Ansprüchen Dritter freistellen.
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 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.
Note
Die Datenübertragung berücksichtigt nicht die strikte Trennung nach Mandanten. Alle Adressdaten können über einen Mandanten geliefert werden. Es besteht die Möglichkeit, je Mandant einzelne SFTP-Konten zu verwenden, wenn hier eine sichere Trennung gewährleistet sein muss. Alternativ können Sie in einem Mandanten mehrere Unterverzeichnisse anlegen. Beachten Sie in beiden Fällen, dass der Empfängerdaten-Import eine Datei je Mandant beziehungsweise Unterverzeichnis bereitstellen muss.
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.csvDie Empfängerdatei selbst ist eine CSV-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.
Note
Gemäß der Spezifikation müssen alle Felder der Hauptempfängerliste übertragen werden. Felder, die ohne Wert bleiben sollen, werden als Leerspalte übertragen. Sowohl die Existenz eines Feldes als auch die Reihenfolge der Felder ist vorgegeben. Verändern Sie diese nicht ohne Zustimmung aller Parteien.
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.
Note
Um personalisierte Inhalte nutzen zu können, benötigen Sie eine neue Vorlage. Wenden Sie sich an die Kundenbetreuung.
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.
Note
Mit der REST-API erstellte Mailings können Sie nicht für die Closed-Loop-Schnittstelle verwenden. Erstellen Sie das Ursprungs-Mailing ausschließlich in Smart Campaigns.
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.
Note
Der Mailing-Versand wird ausschließlich über das Ablegen einer Datei auf dem für die Closed-Loop-Schnittstelle eingerichteten Server ausgelöst. Der Versand über die Optimizely Campaign Benutzeroberfläche ist nicht möglich.
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 |
|---|---|---|---|
Varchar(255) | 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 |
Note
Der Listenaufbau ist nur ein Vorschlag und wird bei Bedarf um die entsprechenden Felder erweitert. Wenden Sie sich im Voraus an die Kundenbetreuung und vermerken Sie die Felder in der Schnittstellendefinition.
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.
Tip
In der folgenden Dokumentation werden Beispieldateinamen verwendet. Sie können die Dateinamen frei konfigurieren.
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 | 2021-01-01 12:07:55 |
|
finished | Endzeitpunkt des Mailings | 2021-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 |
| |
created | Versandzeitpunkt | 2021-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
- SOFT - Soft-Bounce | | | 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 |
| |
created | Klick-Zeitpunkt:::hint{style="info"} | | |
Note | | | |
Ein Benutzer kann mehrfach innerhalb einer Sekunde klicken. ::: | 2021-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 |
| |
created | Öffnungszeitpunkt:::hint{style="info"} | | |
Note | | | |
Ein Benutzer kann ein Mailing mehrfach öffnen. Es werden dann mehrere Datensätze generiert. ::: | 2021-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 |
| |
created | Öffnungszeitpunkt | 2021-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 |
| |
created | Zeitpunkt der Abbestellung | 2021-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 |
| |
created | Zeitpunkt des Rückläufers | 2021-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 | |