Eine der größten Stärken des Cambuildr ist, Aktionen aus unterschiedlichsten Quellen einspielen zu können. Das funktioniert am Einfachsten über die API, und zwar über unsere Action-Schnittstelle.
Dabei gibt es vier entscheidende Werte, die jede Action enthalten sollte:
E-Mail-Adresse (data.email)
Die E-Mail-Adresse dient als Identifikation des Users. Sie ist der einzige unbedingt erforderliche Wert. Ist eine Person noch nicht in der Datenbank vorhanden, wird sie neu angelegt.
Name der Aktion (data.actions[0].name)
Der Name der Aktion beschreibt die Tätigkeit des User an sich. Zur besseren Verständlichkeit bei Selektionen sollten Aktionen immer Verben in der Vergangenheitsform sein, zum Beispiel: angemeldet, gekauft, abonniert, bestellt, heruntergeladen, …
Kontext der Aktion (data.actions[0].context)
Der Kontext beschreibt das Objekt, auf das sich die Aktion bezieht. Beispiele: Newsletter, Seminar, Workshop, Produkt, Produktupdates, Infomaterial, Folder, …
Quelle (data.actions[0].source)
Die Quelle gibt Auskunft darüber, wo genau die Aktion stattgefunden hat. Beispiele: Startseite, Detailseite Veranstaltungs-Seite, Fortbildungs-Seite, Detailseite Produkt B, Landingpage Aktion Februar, Landingpage Promotion Juli
Wir empfehlen, eine Übersicht über alle selbst eingerichteten Aktionen zu führen – das hilft, den Überblick zu bewahren. Ein einfaches Spreadsheet kann übersichtstechnische Wunder wirken:
Beschreibung | Aktion | Kontext(e) | Quelle(n) |
Newsletter-Anmeldungen (auf jeder Seite im Footer möglich) | angemeldet | Newsletter | Titel der Seite |
Veranstaltungs-Anmeldungen (Workshops & Seminare) | angemeldet | Seminar, Workshop | Name des Seminars/Workshops |
Käufer von Produkten oder Dienstleistungen | gekauft | Produkt, Dienstleistung | Name des Produkts/der Dienstleistung |
Disclaimer
Es gibt die Möglichkeit, im Cambuildr mitzutracken, ob beim Signup ein Disclaimer akzeptiert wurde. Diese Information wird dann bei der Action-Übersicht der jeweiligen Person angezeigt. Dafür müssen innerhalb der Action die beiden Attribute disclaimer_accepted (mit dem Wert true, falls akzeptiert) und disclaimer_text (mit dem Text des entsprechenden Disclaimers) mitgeschickt werden (siehe mögliche Parameter).
Technische Dokumentation
Beispiel-Request
Zum Speichern der Daten ist ein HTTP-Post notwendig, der JSON an den CamBuildr schickt. Es wird zumindest die E-Mail-Adresse benötigt; wir würden auch die Übergabe einer Action empfehlen, um die Personen im Cambuildr dann gezielt selektieren zu können. Ein Minimalbeispiel wäre folgendes:
HTTP-POST:
https://{Cambuildr-Url}/api/v1/people
{
"email" : "[email protected]",
"actions" :
[
{
"name": "eingetragen", // Action Verb: Was wurde gemacht?
"context": "Newsletter" // Kontext: Worauf bezieht sich die Aktion?
"source": "Titel der Seite" // Quelle: Wo wurde die Aktion gemacht?
"vendor": "Kampagnen-Website", // System, optional
}
]
}
Die Cambuildr-URL kann ganz einfach über die Administrationsmaske des Cambuildr eingesehen werden, sie umfasst den Rot umrandeten Teil im folgenden Screenshot:
Die komplette URL für den Beispielrequest wäre in diesem Falle also https://demo.cambuildr.com
Der Request als cURL würde folgendermaßen aussehen:
curl --location --request POST 'https://demo.cambuildr.com/api/v1/people' \
--header 'Content-Type: application/json' \
--data-raw '{ "email": "[email protected]", "actions": [ { "name": "eingetragen", "context": "Newsletter", "source": "Titel der Seite", "vendor": "Kampagnen-Website" } ] }'
Beispiel-Request Javascript
Das folgende Javascript-Snippet sendet den selben Beispiel-Request bei Form-Submit ab:
document.getElementById('form').addEventListener('submit', (event) => {
event.preventDefault();
var data = JSON.stringify({ "email": "[email protected]", "actions": [{ "name": "eingetragen", "context": "Newsletter", "source": "Titel der Seite", "vendor": "Kampagnen-Website" }] });
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function() {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://demo.cambuildr.com/api/v1/people");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(data);
});
Mögliche Parameter
HTTP-POST: https://{Cambuildr-Url}/api/v1/people
{
"name" : "Markus", // Vorname, optional
"surname" : "Mustermann" // Nachname, optional
"email" : "[email protected]", // Mail-Adresse, erforderlich
"actions" :
[
{
"name": "eingetragen", // Action Verb: Was wurde gemacht?
"context": "Newsletter" // Kontext: Worauf bezieht sich die Aktion?
"source": "Titel der Seite" // Quelle: Wo wurde die Aktion gemacht?
"tags": ["Thema A", "Thema B"], // Tags der Aktion, optional
"vendor": "Kampagnen-Website", // System, optional
"value": 10.00 // Ein Wert, der der Action zugewiesen werden kann. Dieser Wert muss numerisch sein, damit er korrekt in den Selektionen benutzt werden kann.
"custom_key": "custom_value" // beliebige Key-Value-Paare, auf die über den jeweiligen Placeholder %action.custom_key% zugegriffen werden kann
"disclaimer_accepted": true, // Wenn der Disclaimer beim Signup akzeptiert wurde
"disclaimer_text": "Ich stimme dem Disclaimer zu..." // Text des Disclaimers
}
],
"tags":[
{ "screen_name":"tagname" }
],
"gender": "m", // Geschlecht, optional (m oder f)
"birthdate": "YYYY-MM-TT", //Geburtstag
"phone": "+43 1 5323201", //Telefonnummer
"address": { // Anschrift, optional
"street" : "Gölsdorfgasse 4/6",
"city" : "Wien",
"zip_code" : "1010",
"country_alpha2" : "AT"
},
"custom_fields":
[
{
"name": "Custom Field Eins Name",
"value": "Custom Field Eins Wert"
},
{
"name": "Custom Field Zwei Name",
"value": "Custom Field Zwei Wert"
}
],
"social_connectors": [{
"name": "custom",
"foreign_id": "12345",
"social_user_name": "External Name"
}]
}
Wenn Custom Fields über diese API gespeichert werden sollen, müssen diese zuvor bereits im CamBuildr existieren. Andernfalls wird ein Fehler '412 Precondition Failed' mit weiteren Informationen im Body zurückgegeben.
Das folgende File beinhaltet einen Beispiel-Request, der in Postman importiert werden kann: SupportheroCalls.postman_collection (2)
Achtung
Wenn tags (auch mit einem leeren Array) geschickt werden, und die Route mit einem authentifiziert User aufgerufen wird, werden alle Tags, die nicht mit dem Request geschickt werden, von dem Kontakt entfernt!