Allgemeine Beschreibung Das Customer Profile Interface ist eine Schnittstelle zur Übergabe von Kontaktprofildaten aus Webseiten wie z.B. Anmeldeseiten, Abmeldeseiten und ähnlichem. Mit einfachen Steuerparametern können hier Profilfelder in der Datenbank eines Mandanten befüllt oder aktualisiert werden. Diese Schnittstelle kann keine Kampagnen steuern, Inhalte übermitteln oder ähnliches. Typische Prozesse sind

  • Anmeldung
  • Abmeldung
  • Profiländerung
Die Kommunikation und der Datenaustausch erfolgt unter Verwendung von HTTP POST-Requests. Je nach Mandant Konfiguration sind weitere vom System ausgelöste Folgeaktionen möglich. Diese sind
  • Versendung einer Confirm E-Mail
  • Versendung einer Double-Optin E-Mail
  • Versendung diverser Notifier E-Mails and eine/mehrere fest definierte E-Mail Adressen

Kommunikation und Datensicherheit

Die CPI Schnittstelle ist zur Kommunikation mit externen DV-Systemen über das HTTPS Protokoll ansprechbar, das den verschlüsselten Austausch der Daten ermöglicht. Darüber hinaus ist der Zugriff auf die CPI Schnittstelle durch ein accountabhängiges Authentifizierungsverfahren geschützt. Jede Transaktion, die über die CPI Schnittstelle erfolgt wird vom System protokolliert.

POST Parameter

Jede Üertragung benötigt folgende Parameter zur Authentifizierung:
ent,Account ID
usr,Login
Mit dem nächsten Parameter wird definiert um was für eine Art von Übertragung es sich handelt: Anmeldung oder Abmeldung. Ohne diesen Parameter ist eine Übertragung nicht möglich.
p_status, Wert: A = Anmeldung | Wert: U = Abmeldung (Unsubscribe)
Als letztes Pflichtfeld folgt die E-Mail Adresse. Die E-Mail Adresse darf nicht leer sein und wir auf Syntaxfehler überprüft. Sollte die übertragene E-Mail Adresse nicht valide sein so wird die Übertragung abgebrochen.
email, E-Mail Adresse

Optionale Parameter – Datenanreicherung

salut Anrede (Salutation) (Alphanumerisch / Max 100 Zeichen) Alternativ kann als Wert 1, 2 oder 3 übertragen werden. In solch einem Fall wandelt die CPI Schnittstelle die übertragenen Werte automatisch wie folgt um: 1,Sehr geehrter Herr 2,Sehr geehrte Frau 3,Sehr geehrte Damen und Herren. Die automatische Umwandlung kann auch vom jeweiligen Account Manager deaktiviert werden. title Titel (Alphanumerisch / Max 255 Zeichen) fname Vorname (Firstname) (Alphanumerisch / Max 50 Zeichen) lname Nachname (Lastname) (Alphanumerisch / Max 50 Zeichen) format Newsletter Format – Wert: H = HTML | Wert: T = Text | Wert: M = Multipart. Wird dieser Parameter nicht übertragen wird er automatisch auf M gesetzt. Das Format steuert den Newsletter Format welcher beim Newsletter Versand an diese Person verwendet wird. Wird ein anderer Wert als H, T oder M übertragen so wird diese Person keine E-Mails von XQ:Campaign empfangen können! street Straße (Alphanumerisch / Max 140 Zeichen) city Stadt (Alphanumerisch / Max 60 Zeichen) zip Postleitzahl (Alphanumerisch / Max 20 Zeichen) country Land (Alphanumerisch / Max 255 Zeichen) company Firma (Alphanumerisch / Max 255 Zeichen) geb Geburtstag (Format YYYY-MM-DD) Alternativ können auch folgende Parameter übertragen werden: geburtsjahr, geburtsmonat, geburtstag. Diese Parameter werden automatisch in das richtige Format umgewandelt. ext_id External ID (Alphanumerisch / Max 20 Zeichen). Es sollte von Anfang an definiert werden auf welchem Parameter der Primärschlüssel liegt und auf keinen Fall von Übertragung zu Übertragung geändert werden, da es ansonsten zu ungewollten Adressdubletten kommt. Bei einer Übertragung prüft die CPI Schnittstelle anhand der E-Mail Adresse ob ein solcher Datensatz bereits vorhanden ist. Falls ja, so wird kein neuer Datensatz angelegt sondern der bestehende mit den neuen Parametern aktualisiert (Profiländerung). Wenn die E-Mail Adresse nicht als Primärschlüssel fungieren soll, so kann der Parameter ext_id verwendet werden. Wird dieser Parameter übertragen, so wird der Abgleich ob der Datensatz bereits vorhanden ist ausschließlich anhand dieser ID vorgenommen und im negativen Falle der Datensatz neu angelegt, auch wenn die E-Mail Adresse bereits vorhanden ist!

Optionale Parameter – Rückgabeverhalten

Folgende Parameter steuern die Rückgabe / das Verhalten der CPI Schnittstelle nach der Übertragung. Es gibt zwei primäre Einsatzmöglichkeiten für die Einbindung der CPI Schnittstelle. A: HTML Formular Zielseite (POST action) redirect_check URL für Weiterleitung falls eine invalide E-Mail Adresse angegeben wurde. Falls dieser Parameter nicht übertragen wird, wird immer bei diesem Fehlerfall auf redirect_error weitergeleitet. redirect_ok URL für Weiterleitung falls keine Fehler aufgetreten sind redirect_error URL für Weiterleitung falls Fehler aufgetreten sind update_ok URL für Weiterleitung bei erfolgreichem Datensatzupdate B: Im Hintergrund durchgeführte POST Requests ret Mit ret wir die Formatierung des Rückgabewertes gesteuert. Mögliche Werte sind: xml – Die Rückgabe erfolgt XML formatiert; html – die Rückgabe erfolgt HTML formatiert cd Es wird ein Status Code übermittelt (0,1,2) 0 = OK, 1 = Fehler, 2 = Update update_ok Wert: on – wird dieser Parameter nicht übermittelt, wird keine Unterscheidung zwischen neuem Datensatz und Update gemacht. In beiden Fällen kommt ein OK zurück. Mit diesem Parameter werden unterschiedliche Status Codes zurückgegeben.

POST Spezial-Parameter

Mit diesen Spezial Parametern kannst Deine Mandant Konfiguration dynamisch erweitern oder übertragunsspezifische Aktionen durchführen. email_neu Neue E-Mail Adresse. Funktioniert nur in Kombination mit dem Parameter email. Beide Parameter müssen übermittelt werden und unterschiedliche Werte aufweisen. Somit kannst einem bestehendem Datensatz eine neue E-Mail Adresse zuordnen. charset Angabe der Codierung der übertragenen Parameter. z.B. UTF-8 Wenn die Daten UTF-8 codiert an die CPI übertragen werden sollen, muss dieser Parameter übermittelt werden. Ansonsten können die Daten nicht korrekt in XQ:Campaign dargestellt werden. Das Charset ist per Default auf iso-8859-1 gestellt und muss deshalb im Regelfall nicht explizit angeben werden. ono Wert: 1. Mit diesem Parameter kann die mandantenseitige Konfiguration von Confirmed oder Double Opt-In unterdrückt werden. Die übertragenen Datensätze werden sofort aktiv im Mandant bereitgestellt und erhalten keine Confirmed oder Double Opt-In E-Mail. Bitte beachte, dass nach deutschem Recht Anmeldungen ohne Double Opt-iin Prozess nicht erlaubt sind. gosin Wert: 1. Mit diesem Parameter kann die mandantenseitige Konfiguration umgangen werden. Dieser Parameter muss in Kombination mit ono (Wert 1) übemittelt werden und erzwingt die Aussendung einer Confirmed Opt-In E-Mail, auch wenn im Mandant das Double Opt-In Verfahren aktiviert ist. no_update Wert: 1. Dieser Parameter verhindert das Aktualisieren der Stammdaten eines bereits vorhandenen Datensatzes. Es werden lediglich der Status und das CHANGEDATE aktualisiert d_optin_altbody Wert: 1. Aktivieren des im Mandanten hinterlegten Alternativ Textes für die Double Opt-In E-Mail d_optin_altsubject Wert: 1. Aktivieren des im Mandanten hinterlegten Alternativ Betreffs für die Double Opt-In E-Mail lang Wert: Alphanummerisch. Double Opt-In Konfigurationen können als sogenannte LANG Pakete gespeichert werden. Dies ermöglich es in einem Mandanten unterschiedliche Double Opt-In Texte zu speichern. Mit dem Parameter wird das gewünschte Sprachpaket aktiviert. no_welcomemail Wert: 1. Unterdrückt die Versendung einer Welcome-Mail, auch wenn diese im Mandant eingeschaltet wurde. follow_mail Wert: 1. Aktiviert die Aussendung einer Followmail. Followmail muss für den Mandanten zuvor aktiviert worden sein. follom_mail_eid Wert: Integer. Kann nur in Kombination mit follow_mail verwendet werden. Beinhaltet die ID eines Newsletters, welcher als Vorlage für die Followmail verwendet wird.

POST Profil-Parameter

Neben den Stammdaten ist es auch möglich sogenannte Profiloptionen zu übertragen. Profiloptionen erweitern die Stammdaten um kundenspezifische Informationen zu jedem einzelnen Datensatz. Beispiele für Profiloptionen sind: Alter, Schuhgröße, Telefonnummer usw. Es können pro Account beliebig viele Profiloptionen angelegt werden. Jede Profiloption kann bis zu 255 alphanumerische Zeichen beinhalten und erhält eine eindeutige ID. Der Parameter Name beginnt immer mit „pp“ gefolgt von der ID, z.B. pp1000, pp1001, pp1002, … Zustätzlich wird ein weiterer Parameter benötigt welcher der CPI Schnittstelle mitteilt, welche Profiloptionen übertragen werden. Der Parameter heißt options und enthält als Werte eine kommagetrennte Liste aller zu übertragenden Profiloptions-IDs. Die IDs werden hierbei ohne den pp-Präfix angegeben:
options => 1000,1001,10002

Veraltete Variablen

Aus historischen Gründen sind diverse Variablen in Verwendung, die heute so keine Anwendung mehr finden oder anders benannt sind. Damit diese Variablen in bereits eingesetzten angebundenen Seiten weiter funktionieren, werden diese von der CPI bei Übergabe automatisch als heute gültige Variable interpretiert.
Veraltete Variable Aktuelle Variable Anmerkungen
$entity_id $ent
$usr $login_username
$u $login_username
$pwd $p $login_password
$redirect_ok $red_ok $rd_ok redirect URL bei erfolgreicher Datenübergabe
$redirect_error $red_error $redirect_err $rd_err redirect URL bei allgemeinem Fehler
$update_ok $upd_ok redirect URL bei erfolgreichem Update
$redirect_check $red_check $rd_check chk_data wenn falsche Benutzereingabe (falsche E-Mail Adresse)
$redirect_una $red_una $rd_una $unsub_na wenn Fehler bei Abmeldung weil Benutzer nicht vorhanden bzw. nicht aktiv
$email $adr $email_neu $addr E-Mail Adresse – ACHTUNG: $email_neu wird nur interpretiert wenn $addr nicht vorhanden ist. Ansonsten existieren beide Variablen parallel!
$salutation $salut Anrede
$fname $f $firstname Vorname
$lname $l $lastname Nachname
$person_status $p_status Status (Kontakt)
$firma $company Firma
]]>

English EN Deutsch DE