Skip to main content
Die Data API ist eine REST-API, die auf den Remote-Servern von Kameleoon gespeicherte Daten abruft oder schreibt. Verwenden Sie die verfügbaren Endpoints, um:
  • Besuchsereignisse für einen bestimmten Besucher abzurufen.
  • Zusätzliche Besuchsereignisse für einen bestimmten Besucher zu senden, wie zum Beispiel Offline-Konversionsereignisse.
  • Produktdaten für einen bestimmten Sitecode zu senden und abzurufen.
  • Zusätzliche Daten für einen bestimmten Besucher zu speichern, wie zum Beispiel CRM- oder Segmentierungsdaten.

​
Data API in Postman testen

Testen Sie Data-API-Anfragen ohne Code mit der Kameleoon-Data-API-Collection in Postman. Die Collection enthält eine Anfrage pro Endpoint, und jede Anfrage gibt eine 200-Antwort zurück, sobald Sie die Variablen festgelegt haben. So verwenden Sie die Collection:
  1. Laden Sie die Kameleoon-Data-API-Collection als ZIP-Archiv herunter, entpacken Sie die JSON-Datei und importieren Sie sie in Postman.
  2. Legen Sie im Tab Variables der Collection baseUrl auf den Host Ihres Projekts und siteCode auf den Site-Code Ihres Projekts fest.
  3. Um POST /visit/forget aufzurufen, tragen Sie zusätzlich clientId und clientSecret ein, die Sie über den Authentifizierungsablauf der Automation API erhalten, und senden Sie dann Get access token. Die Anfrage speichert das Token in der Variable accessToken.
  4. Senden Sie eine beliebige andere Anfrage.

​
Data-API-Endpoints

Die Endpoints lassen sich in drei Hauptkategorien von Daten einteilen:

​
Visit-Endpoints

Die Visit-Endpoints rufen Ereignisse (Conversions, Custom Data, Segmente und mehr) für einen bestimmten Besuchercode ab und senden sie. Verwenden Sie diese Endpoints, um Offline-Kaufdaten, wie zum Beispiel Einkäufe im stationären Handel, in Kameleoon zu importieren.
  • GET /visit/visitor: Dieser Endpoint ruft die von Kameleoon erfassten Besuchsdaten ab, wie zum Beispiel Experimente und Personalisierungen, die für den Benutzer ausgelöst wurden, oder gezielte Segmente.
Der Zugriff auf diesen Endpoint erfordert die Kameleoon-Lösung Feature Experimentation. Weitere Informationen erhalten Sie beim Customer Success Manager.
  • POST /visit/forget: Dieser Endpoint entfernt Daten für mehrere Besucher. Der Endpoint erfordert immer eine Authentifizierung. Rufen Sie ihn daher von Ihren Servern aus auf, niemals aus einem Browser.
  • POST /visit/events: Dieser Endpoint sendet Daten für einen bestimmten Besucher, wie zum Beispiel Konversions- und Seitenaufruf-Ereignisse.

​
Product-Endpoints

Die Product-Endpoints rufen Produktdaten für einen bestimmten Sitecode ab und senden sie. Verwenden Sie diese Endpoints, um produktbezogene Ereignisse wie Ansichten, Hinzufügen zum Warenkorb oder Kaufereignisse zu registrieren oder um Statistiken zu bestimmten Produkten abzurufen, wie historische Kauf- oder Aufrufzahlen.
  • POST /product/events: Dieser Endpoint sendet Produktattribute und Ereignisse (Ansicht, Hinzufügen zum Warenkorb und Kauf) für mehrere Produkte. Die Activation API verwendet die Methoden obtainProductData und obtainProductInteractions, um diese Daten abzurufen und für Targeting oder Empfehlungen zu verwenden.
  • GET /product/productCounters: Dieser Endpoint ruft Zählwerte (Anzahl der Aufrufe, Mengen im Warenkorb, Transaktionsmengen) für mehrere Produkte ab.
  • GET /product/productData: Dieser Endpoint ruft Attribute für mehrere Produkte ab.
Sie benötigen Zugriff auf das Product Recommendation-Modul oder das Product Targeting-Add-on. Beide lassen sich in die Lösung Web Experimentation integrieren. Weitere Informationen erhalten Sie vom Customer Success Manager.

​
Map-Endpoints

Die Map-Endpoints speichern zusätzliche Daten für einen bestimmten Schlüssel (in der Regel ein Besuchercode oder eine interne User-ID). Die Activation API und alle SDKs verwenden die Methode retrieveDataFromRemoteSource, um diese Daten abzurufen und für Targeting und Segmentierung zu verwenden. Verwenden Sie den map-Endpoint, um gespeicherte Daten für einen bestimmten Schlüssel abzurufen.
  • GET /map/map: Dieser Endpoint ruft Daten für einen bestimmten Schlüssel ab.
  • GET /map/maps: Dieser Endpoint ruft Daten für mehrere Schlüssel ab.
  • POST /map/maps: Dieser Endpoint sendet Daten für mehrere Schlüssel.

​
Data-API-Hosts

Data-API-Anfragen gehen an einen Host, der von der Region und der Domain Ihres Projekts abhängt. Kameleoon hostet Projekte in Europa und Nordamerika, und jede Region hat einen Host auf der Domain kameleoon.io und auf der Domain kameleoon.eu. Eine Anfrage an den Host der falschen Region erhält eine HTTP-308-Weiterleitung an den richtigen Host. Um die Weiterleitung zu vermeiden, verwenden Sie den Host aus dem Location-Header als Basis-URL.

​
Domain auswählen

Beide Domains führen zu denselben Servern, die Domain ändert also nicht, wie sich Anfragen verhalten. Neuere Projekte verwenden kameleoon.io, ältere Projekte verwenden kameleoon.eu. Verwenden Sie die Domain, die zum Code-Snippet Ihres Projekts passt.

​
Ihre Domain finden

So finden Sie die Domain Ihres Projekts:
  1. Klicken Sie auf Admin > Projects > Edit > Setup.
  2. Suchen Sie in Ihrem Code-Snippet die src-Adresse, die wie //<siteCode>.kameleoon.io/engine.js aussieht.
  3. Lesen Sie die Domain hinter Ihrem Site-Code: kameleoon.io oder kameleoon.eu.

​
Authentifizierung und Ratenbegrenzung

​
Authentifizierung

Standardmäßig erfordern die meisten Data-API-Endpoints keine Authentifizierung, da die Data API die Web-Experimentation-Engine beim Abrufen historischer Daten unterstützt. Die Ausnahme ist POST /visit/forget, das immer eine Authentifizierung erfordert. Für die Authentifizierung verwendet die Data API denselben Ablauf wie die Automation API mit JSON Web Tokens. Wahren Sie die Sicherheit und schützen Sie Ihre API-Anmeldedaten, indem Sie die Authentifizierung für bestimmte Anfragetypen verwenden:
  • Serverseitige Quellen: Für Anfragen, die von Ihren Servern stammen, empfiehlt Kameleoon die Authentifizierung dringend, da sie die Ratenbegrenzungen erhöht. Authentifizieren Sie sich, wenn Sie serverseitige SDKs mit Feature Experimentation verwenden.
  • Clientseitige Quellen: Für Anfragen, die von einer Clientanwendung wie einem Webbrowser stammen, bei denen API-Anmeldedaten offengelegt werden könnten, sollten Sie sich nicht authentifizieren. Kameleoon empfiehlt diese Konfiguration bei der Verwendung von Web Experimentation nicht. Clientseitige Quellen können POST /visit/forget nicht aufrufen, da dieser Endpoint ein Token erfordert. Rufen Sie ihn nur von Ihren Servern aus auf.
Jede Anfrage, die ein API-Token mit falschem Format, ein abgelaufenes Token oder eine ungültige Signatur bereitstellt, führt zu einer HTTP-401-Antwort „Unauthorized”. Weitere Informationen zum Authentifizierungsprozess finden Sie in der Dokumentation Automation API Authentication Flow.
Wenn Sie ausschließlich Feature Experimentation und serverseitige SDKs verwenden, kontaktieren Sie den Customer Success Manager, um die Authentifizierung für bestimmte Endpoints zu aktivieren. Kameleoon bietet eine flexible Einrichtung, um Endpoints zu sichern und die Authentifizierung auf GET- oder POST-Anfragen zu beschränken.

​
Ratenbegrenzungen

Die Data API erzwingt Ratenbegrenzungen basierend auf Ihren vertraglich vereinbarten monatlichen Unique Visitors (MUV) und Ihrer IP-Adresse. Wenn Ihre Anwendung eine dieser Grenzen überschreitet, gibt die API eine HTTP 429-„Too Many Requests”-Antwort zurück. Diese Ratenbegrenzungen stellen sicher, dass der Kameleoon-Service für alle Kunden leistungsfähig und zuverlässig bleibt. Für serverseitige Quellen können Sie die IP-basierten Begrenzungen durch Authentifizierung aufheben. In Umgebungen, in denen viele Besucher eine einzige IP-Adresse teilen, etwa in Büros oder Unternehmensnetzwerken, können die IP-basierten Begrenzungen auch dann greifen, wenn Ihre MUV im Rahmen des Vertrags bleiben. Der Wert von multiplier hängt von Ihrem Abonnement ab:
  • 1 — Sie nutzen nur eine Lösung, entweder Web Experimentation oder Feature Experimentation
  • 2 — Sie nutzen sowohl Web Experimentation als auch Feature Experimentation
Wenn Sie für Ihren Anwendungsfall höhere Ratenbegrenzungen benötigen, wenden Sie sich bitte an Ihren Account Manager, um weitere Informationen zu erhalten.
Kameleoon erkennt bekannten Bot-Traffic automatisch und schließt ihn von der Berechnung der Ratenbegrenzungen aus. Anfragen, die als von Bots stammend identifiziert werden, zählen nicht zu den GET- oder POST-Limits in der obigen Tabelle.

​
Was Anfragen generiert

Das Verständnis, welche Operationen GET- und POST-Anfragen generieren, hilft Ihnen, den Verbrauch Ihres Rate-Limits zu schätzen und zu verwalten. Die folgende Aufschlüsselung gilt hauptsächlich für clientseitige Technologien (engine.js, das JavaScript SDK und mobile SDKs), bei denen jedes Gerät eigene Anfragen sendet. Für POST-Tracking-Anfragen sind serverseitige SDKs bei großen Datenmengen effizienter, da sie Daten mehrerer Besucher in einer einzigen Anfrage bündeln können; GET-Anfragen richten sich immer an einen einzelnen Besucher. Ihre Anwendung löst GET-Anfragen nur aus, wenn sie explizit einen der folgenden Vorgänge aufruft. Das SDK und der Engine führen kein automatisches Polling durch:
  • Besucherdaten-Abruf: getRemoteVisitorData() (SDKs) oder performRemoteSynchronization() (engine.js) laden Remote-Besucherdaten für einen bestimmten Besucher bei Bedarf.
  • Remote-Daten- und Warehouse-Audience-Abruf: getVisitorWarehouseAudience() (SDKs) oder retrieveDataFromRemoteSource() (SDKs und engine.js) laden Data-Warehouse- oder Remote-Map-Daten bei Bedarf.
POST-Anfragen stammen vom Tracking-Mechanismus, der Besucherdaten vor dem Senden bündelt:
  • Tracking-Anfragen: Der primäre wiederkehrende POST-Aufruf. Das SDK oder der Engine bündelt ausstehende Besucherdaten und sendet sie höchstens einmal pro Tracking-Intervall, jedoch nur wenn Daten ausstehen. Das Standardintervall beträgt 1 Sekunde. In SDKs können Sie das Intervall zwischen 1 und 5 Sekunden mithilfe von trackingIntervalMillisecond / tracking_interval_millisecond konfigurieren; engine.js verwendet ein festes Intervall von 500 Millisekunden. Konversionen, getrackte Feature-Flag-Auswertungen und explizite flush()-Aufrufe stellen Daten für das nächste Intervall in die Warteschlange, oder senden sie sofort, wenn Sie einen sofortigen Flush auslösen.
  • Activity-Tracking: Ein sekundärer Mechanismus, der Besucheraktivitätsdaten (Klicks, Scrollvorgänge und Mausbewegungen) in den nächsten Tracking-Versand einbindet. Das SDK sammelt Aktivitätsdaten nur, wenn der Benutzer auf dem aktiven Tab aktiv ist. Das Standardintervall beträgt 60 Sekunden. In SDKs können Sie das Intervall mithilfe von activityTrackingIntervalMillisecond / activity_tracking_interval_millisecond konfigurieren; engine.js verwendet ein festes Intervall von 60 Sekunden.
Für mobile SDKs: Das periodische Tracking wird automatisch angehalten, wenn die App in den Hintergrund wechselt. Ein expliziter sofortiger Flush kann unabhängig vom App-Status noch ausstehende Daten senden. Für das JavaScript SDK: Die Tracking-Anfrage wird nur gesendet, wenn der Besucher seit dem letzten Intervall-Tick tatsächlich mit der Seite interagiert hat (durch Mausbewegung oder Scrollen), was verhindert, dass ausgeblendete oder in den Hintergrund versetzte Tabs die Besuchsanzahl aufblähen. Um weiterhin Daten zu senden, wenn die Seite nicht aktiv ist, rufen Sie flush({instant: true}) explizit auf. Wenn die Kameleoon Engine (window.Kameleoon) ebenfalls auf der Seite vorhanden ist, verhindert das SDK eine doppelte Activity-Tracking-Erfassung.

​
Kontoweite Limits

Ratenlimits gelten für Ihr gesamtes Kundenkonto, nicht für einzelne Projekte. Wenn ein Projekt übermäßig viele Anfragen erzeugt (beispielsweise weil eine fehlerhafte Implementierung eine Schleife erstellt, die Custom-Data-Events wiederholt sendet), verbraucht dieses Projekt das gemeinsame Konto-Limit und kann HTTP 429-Fehler in all Ihren anderen Projekten verursachen.

​
Diagnose von übermäßigem Anfragevolumen

Verwenden Sie die Live events-Seite (Insights > Live events), um das Projekt zu identifizieren, das unerwarteten Traffic erzeugt:
  1. Ereignisvolumen nach Projekt prüfen: Wählen Sie jedes Projekt nacheinander aus und prüfen Sie die Ereignisanzahl der letzten Stunde oder 24 Stunden. Ein Projekt, das deutlich mehr Ereignisse erzeugt, als sein Besuchervolumen rechtfertigt (beispielsweise mehrere Millionen Ereignisse bei einem Vertrag mit 100.000 MUV), ist wahrscheinlich die Ursache.
  2. Nach Ereignistyp filtern: Sobald Sie das verdächtige Projekt identifiziert haben, filtern Sie die Ereignisse nach Typ. Custom-Data-Events sind die häufigste Ursache für unerwartetes Volumen. Eine fehlerhafte Implementierung kann eine Schleife erstellen, die dieselbe Custom-Data-Variable oder alle Custom-Data-Variablen bei jedem Seitenaufruf sendet und in kurzer Zeit eine große Anzahl von Ereignissen produziert.

​
Ihre Anfragenanzahl prüfen

Verwenden Sie die Data-API-Request-Endpoints der Automation API, um genau zu sehen, woher Ihr Anfragevolumen an die Data API stammt, bevor es sich Ihrem Rate Limit nähert:
  • Nach Endpoint: GET /data-api-requests/by-endpoint gibt die Anzahl der an die Data API gesendeten Anfragen für eine bestimmte Site zurück, aufgeschlüsselt nach Tag, HTTP-Methode, Pfad und Statuscode. Verwenden Sie diesen Endpoint, um zu erkennen, welche Integration oder welcher Endpoint Ihren Traffic verursacht.
  • Nach Quelle: GET /data-api-requests/by-source gibt die Anzahl der an die Data API gesendeten Anfragen für eine bestimmte Site zurück, aufgeschlüsselt nach Tag und Quelle (Engine, SDK: <name> oder Direct). Verwenden Sie diesen Endpoint, um zu erkennen, welcher Clienttyp Ihren Traffic verursacht.
Beide Endpoints verwenden dieselben drei erforderlichen Query-Parameter:
Der Bereich zwischen from und to darf 7 Tage nicht überschreiten.
Authentifizieren Sie sich mit einem OAuth-2.0-Bearer-Token und folgen Sie dabei demselben Authentifizierungsablauf der Automation API, der auch für andere Automation-API-Aufrufe verwendet wird. So schlüsseln Sie das Anfragevolumen nach HTTP-Methode, Pfad und Statuscode auf:
curl
So schlüsseln Sie das Anfragevolumen nach Quelle auf:
curl
Führen Sie diese Prüfung immer dann aus, wenn Live events unerwarteten Traffic anzeigt, um zu bestätigen, welche HTTP-Methoden, Pfade, Statuscodes oder Quellen Ihr Anfragevolumen ausmachen.