API
Alle Kommunikation mit Clerk erfolgt über die API:
https://api.clerk.io/v2
Die Einrichtung dieser Kommunikation erfordert 4 Schritte, die in dieser Anleitung beschrieben sind. Sie müssen:
- Daten synchronisieren
- Ergebnisse abrufen
- Ergebnisse visualisieren
- Tracking hinzufügen
API-Schlüssel #
Diese Schlüssel werden verwendet, um auf die Daten Ihres Shops zuzugreifen. Sie finden sie in my.clerk.io > Developers > API Keys.
Sie bestehen aus einem öffentlichen Schlüssel, der Zugriff auf Endpunkte gewährt, die nicht sensible Daten bereitstellen, und einem privaten Schlüssel, der es Ihnen ermöglicht, mit den Daten des Shops zu arbeiten und auf sensible Daten wie Kunden- und Bestellinformationen zuzugreifen.
Private Schlüssel können aus Sicherheitsgründen nur einmal nach ihrer Erstellung angezeigt werden, und Sie können so viele Schlüssel erstellen, wie Sie für verschiedene Zwecke benötigen.
1. Daten synchronisieren #
Der erste Schritt besteht darin, Daten einzugeben, damit die KI von Clerk.io Ihren Webshop verstehen und Ergebnisse vorhersagen kann. Clerk synchronisiert jede Webshop-Domain als eigene individuelle Store-Instanz, auf die mit einem Satz von API-Schlüsseln zugegriffen wird.
CRUD-API #
Sie können Ihre Daten über die CRUD-API-Endpunkte synchronisieren, die es Ihnen ermöglichen, Ressourcen auf Abruf zu lesen, erstellen, aktualisieren und löschen.
curl --request POST \
--url 'https://api.clerk.io/v2/products' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"private_key": "osLqDAs5s2tlf3adpLv6Mp1hxx3f",
"products":[
{
"id": 123,
"name": "Green Lightsaber",
"description": "Antique rebel lightsaber.",
"price": 99995.95,
"brand": "Je’daii",
"categories": [987, 654],
"created_at": 1199145600
},
{
"id": 789,
"name": "Death Star Deluxe",
"description": "Death Star. Fool proof."
"price": 99999999999999.95,
"brand": "Imperial Inc.",
"categories": [345678],
"created_at": 11991864600
}
]
}'
Die verfügbaren Objekte sind:
Einer der wichtigsten Unterschiede von Clerk ist, dass es keine Lernphase gibt, da wir ab dem ersten Tag alle vorhandenen Bestellungen nutzen können, um das Verhalten der aktuellen Kunden zu verstehen.
Datenfeeds #
Zusätzlich zur Verwendung der CRUD-API wird dringend empfohlen, eine Backup-Synchronisationsmethode hinzuzufügen. Schließlich kann bei API-Aufrufen vieles schiefgehen.
Ihr Preiserver könnte zum Beispiel abstürzen oder ein Produktattribut einen Fehler enthalten, der mehrere Aufrufe fehlschlagen lässt. Um diese Probleme zu vermeiden, sollten Sie einen oder mehrere Datenfeeds als tägliches Backup für Ihre CRUD-Aufrufe verwenden.
Datenfeeds sind eine oder mehrere JSON-Dateien, die den aktuellen Katalog des Webshops enthalten.
Alle im Feed verfügbaren Daten zum Zeitpunkt des Ladevorgangs sind die, mit denen Clerk arbeitet, mit Ausnahme von Bestellungen, die protokolliert werden und nach dem ersten Import nicht mehr im Feed enthalten sein müssen.
Die Verwendung des Datenfeeds ist auch eine gute Möglichkeit, Clerk mit Bestellungen vorzuladen.
{
"products": [ ... ],
"categories": [ ... ],
"orders": [ ... ],
"customers": [ ... ],
"pages": [ ... ],
"config": {
"created": 1567069830,
"strict": false
}
}
Die Datenfeeds sollten unter einer URL verfügbar sein, auf die der Importer zugreifen kann. Diese konfigurieren Sie im Backend von my.clerk.io unter System status > Data Sync. Sie können den Feed absichern, sodass nur unser Importer Zugriff erhält.
2. Daten abrufen #
Sobald die Daten synchronisiert sind, analysiert die KI diese und erstellt intelligente Indizes, die je nach Anwendungsfall über individuelle Endpunkte abgerufen werden können.
Um zum Beispiel die angesagtesten Produkte abzurufen, können Sie den Endpunkt recommendations/trending verwenden, und um die besten Produkte für eine Suche nach “star wars” anzuzeigen, können Sie den Endpunkt search/predictive verwenden.
Endpunkte #
Alle Endpunkte erfordern, dass Sie den öffentlichen API-Schlüssel mitsenden.
Endpunkte, die Ergebnisse zurückgeben, benötigen außerdem das Argument “limit”, um die Anzahl der zurückgegebenen Ergebnisse zu steuern.
Zusätzliche Parameter hängen vom aufgerufenen Endpunkt ab. Für die besten Alternativen benötigen Sie beispielsweise products, eine Liste von Produkt-IDs für die Suche nach Zubehör, und für alle suchbezogenen Aufrufe wird der Parameter query benötigt, um Übereinstimmungen zu finden.
Die notwendigen Argumente für alle Endpunkte finden Sie in unserer API-Dokumentation.
Standardmäßig gibt die API von Clerk alle verfügbaren Ergebnisse zurück, aber bei Bedarf können Filter verwendet werden, um eine Teilmenge von Treffern zu definieren.
Search #
Unten sehen Sie ein Beispiel für einen Aufruf eines Search-Endpunkts, um die Top-Produkte für eine Suche nach “star wars” zu finden.
curl --request POST \
--url 'https://api.clerk.io/v2/search/predictive' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"limit": 30,
"query": "star wars",
"labels": ["Search - Predictive"]
}'
Recommendations #
Nachfolgend ein Beispiel für einen Aufruf eines Recommendations-Endpunkts, um die angesagtesten Produkte zu finden.
curl --request POST \
--url 'https://api.clerk.io/v2/recommendations/trending' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"limit": 30,
"labels": ["Homepage - Trending"]
}'
Response-Debugging #
Wenn das Debugging für eine Anfrage aktiviert ist, enthalten API-Antworten ein debug-Array, das in der Reihenfolge anzeigt, wie verschiedene Features die Ergebnisse beeinflusst haben. Jeder Eintrag enthält ein feature, eine menschenlesbare message und strukturierte metadata, die die spezifischen Auswirkungen beschreiben.
{
"status": "ok",
"result": [
"riverbank",
"pretty-tree"
],
"count": 2,
"hits": 2,
"debug": [
{
"feature": "merchandising",
"message": "Applying merchandising campaign: Test-promote-in-results. Any calculated effects are available in the metadata.",
"metadata": {
"promote_in_result": {
"frequency=(2, 0)": {
"promoted_products": [
[
"riverbank"
]
]
}
}
}
},
{
"feature": "merchandising",
"message": "Applying merchandising campaign: test-promote-to-position. Any calculated effects are available in the metadata.",
"metadata": {
"promote_to_position": {
"position=(0, 1)": {
"promoted_products": [
[
"0001",
"FFFF"
]
]
}
},
"adjust_position": {
"FFFF": [
{
"max_depth": 1,
"boost": 100000
}
]
}
}
},
{
"feature": "merchandising",
"message": "Applying merchandising campaign: Test campaign. Any calculated effects are available in the metadata.",
"metadata": {
"boost": {
"SPACER0": -2.0
}
}
}
]
}
3. Ergebnisse visualisieren #
Die Clerk-API gibt bei der Rückgabe von Ergebnissen immer die IDs der gefundenen Treffer zurück.
Um Ihre Daten zu visualisieren, können Sie API-Aufrufe serverseitig durchführen, die IDs der passenden Produkte abrufen und anschließend alle produktspezifischen Informationen von Ihrer Webshop-Plattform oder Ihrem PIM abrufen, bevor Sie sie rendern.
Aufruf
curl --request POST \
--url 'https://api.clerk.io/v2/recommendations/trending' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"limit": 3,
"labels": ["Homepage - Trending"]
}'
Antwort
{
"status": "ok",
"result": [
12793,
13827,
12693
],
"count": 3902,
"facets": null
}
Die Clerk-API kann auch so konfiguriert werden, dass sie alle ressourcenspezifischen Informationen zurücksendet, die Sie an Clerk übermitteln, wie Preise, Markennamen, Kategorie-URLs, Blog-Bilder und mehr.
Hiermit müssen Sie häufig keine Einzelaufrufe an Ihr PIM durchführen, bevor Sie Ergebnisse anzeigen, wodurch Ihre Seite schneller geladen wird.
Aufruf
curl --request POST \
--url 'https://api.clerk.io/v2/recommendations/trending' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"limit": 3,
"labels": ["Homepage - Trending"],
"attributes": ["id", "name", "price", "image", "url"]
}'
Antwort
{
"status": "ok",
"result": [
12793,
13827,
12693
],
"count": 3902,
"facets": null,
"product_data": [
{
"id": 12793,
"image": "https://admin.awesomestore.com/image/14df",
"name": "Baccarat Eye Small Oval Red Vase",
"price": 520.0,
"url": "https://admin.awesomestore.com/product/14df"
},
{
"id": 13827,
"image": "https://admin.awesomestore.com/image/51xs",
"name": "Sabre Transat Garden Green 22cm Soup Spoon",
"price": 13.96,
"url": "https://admin.awesomestore.com/product/51xs"
},
{
"id": 12693,
"image": "https://admin.awesomestore.com/image/62x1",
"name": "Sabre Transat Light Blue 22cm Dinner Fork",
"price": 13.96,
"url": "https://admin.awesomestore.com/product/62x1"
}
]
}
4. Tracking #
Das Tracking muss hinzugefügt werden, damit die KI von Clerk immer auf dem neuesten Stand ist und die Ergebnisse für einen Besucher während seiner Session personalisiert werden können. Dafür sind 4 Schritte nötig:
- Für jeden Besucher eine Session-ID generieren.
- Beschreibende Labels zu API-Aufrufen hinzufügen, die Ergebnisse liefern.
- Klicks eines Besuchers auf von Clerk angezeigte Produkte protokollieren.
- Jede Bestellung, die im Webshop getätigt wird, protokollieren.
Visitor-ID erstellen #
Die Session-ID wird auch als Visitor-ID bezeichnet. Sie ist erforderlich, um die Aktivitäten eines Nutzers während einer Session im Webshop zu protokollieren, einschließlich angeklickter Produkte, Suchanfragen und besuchter Kategorien.
Diese Aktivitäten werden für jeden Shop gespeichert, und Clerk.io gibt sie niemals Shop-übergreifend weiter.
Eine Visitor-ID ist einfach eine Zeichenkette zur Identifikation der Session. Diese kann beliebige alphanumerische Zeichen enthalten; wir empfehlen eine Länge von maximal 8 Zeichen für eine optimale Performance.
Als Beispiel könnten Sie in PHP die Funktion uniqid() verwenden, um IDs zu generieren, die mindestens für die aktuelle Session eindeutig sind. Sobald sie erzeugt wurde, muss diese ID bei allen Aufrufen der Clerk.io-API für das Tracking angegeben werden.
<?php
session_start();
$current_visitor = uniqid(); //Beispiel: "646f1f0584371"
$_SESSION["clerk_visitor_id"] = $current_visitor;
?>
Labels hinzufügen #
Labels müssen bei allen Aufrufen hinzugefügt werden, die Ergebnisse liefern, wie etwa Suchtreffer oder Alternativen auf einer Produktseite. Das Argument labels ist eine Liste mit mindestens einem String, der die beschreibende Kennzeichnung für diesen Aufruf sein sollte.
Wir empfehlen, Labels zu verwenden, die die Seite beschreiben, auf der der Aufruf benutzt wird, sowie die Art der Ergebnisse. Ein Beispiel wäre Homepage - Trending. Dadurch sind sie in der Analyse einfach zu erkennen.
curl --request POST \
--url 'https://api.clerk.io/v2/recommendations/trending' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"limit": 30,
"labels": ["Homepage - Trending"],
"visitor": $_SESSION["clerk_visitor_id"]
}'
Klicks protokollieren #
Sie sollten jeden Klick auf ein Clerk.io-Produkt mit dem Endpunkt log/click protokollieren.
Wichtig ist, dass Sie diesen Aufruf nur dann machen, wenn das angeklickte Produkt tatsächlich von Clerk.io angezeigt wurde und nicht vom Webshop selbst. Andernfalls würde es so aussehen, als ob alle Produkte über Clerk gefunden wurden.
Der Aufruf sollte auch api enthalten, also den Endpunkt, der genutzt wurde, um das Produkt anzuzeigen, und product, also die ID des angeklickten Produkts.
Search & Recommendations #
Das Klick-Logging erfolgt, indem Sie je nach verwendeten Endpunkt die Parameter zum Aufruf hinzufügen. Dies ist einfach, da es auf Daten beruht, die Sie bereits selbst eingerichtet haben.
curl --request POST \
--url 'https://api.clerk.io/v2/log/click' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"labels": ["Homepage - Trending"],
"api": "recommendations/trending",
"visitor": $_SESSION["clerk_visitor_id"],
"product": 12793
}'
Email Recommendations #
Das Klick-Logging funktioniert hier anders, da Sie die Daten von GET-Anfragen erhalten, die von Clerk.io weitergeleitet werden. Sie sollten prüfen, ob die URL Parameter enthält, die darauf hindeuten, dass Besucher von einer Email Recommendation auf eine Produktseite gelangen.
Diese Anfragen enthalten immer folgende Query-Parameter:
{
"utm_source": "clerk",
"utm_medium": "email",
"utm_campaign": "Welcome Email - Bestsellers",
"utm_content": "clerk-recommendations",
"clerk_product": 12793,
"clerk_labels": "Welcome Email - Bestsellers",
"clerk_api": "recommendations/popular",
"clerk_n": 0,
"clerk_external": 1
}
Wir empfehlen, zu prüfen, ob die URL clerk_external: 1 enthält, und falls ja, den Klick mit den erhaltenen Daten zu protokollieren.
clerk_api enthält den API-Endpunkt mit einem *-Zeichen, um Codierungsprobleme zu vermeiden. Beim Logging des Klicks sollte dies durch / ersetzt werden. external: 1 sollte dem Aufruf hinzugefügt werden, damit Clerk erkennt, dass der Klick aus einer E-Mail stammt.
Hier ein Beispielaufruf für log/click, der die o. g. Daten nutzt:
curl --request POST \
--url 'https://api.clerk.io/v2/log/click' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"labels": ["Welcome Email - Bestsellers"],
"api": "recommendations/popular",
"visitor": $_SESSION["clerk_visitor_id"],
"product": 12793,
"external": 1
}'
Produkte protokollieren #
Wenn Besucher Produktseiten ansehen, sollte dies protokolliert werden, damit die Ergebnisse personalisiert werden können – insbesondere die besucherbezogenen wie Visitor Recommendations oder Visitor Alternatives.
Wenn Sie Endpunkte verwenden, die bereits die Produkt-ID benötigen, wie z. B. recommendations/substituting oder recommendations/complementary, wird die Produkt-ID von Clerk.io automatisch protokolliert.
Andernfalls müssen Sie einen separaten Aufruf an log/product machen, mit der ID des angesehenen Produkts.
curl --request POST \
--url 'https://api.clerk.io/v2/recommendations/trending' \
--header 'accept: application/json' \
--header 'content-type: application/json'
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
"visitor": $_SESSION["clerk_visitor_id"],
"product": 12793
}'
Verkäufe protokollieren #
Die KI von Clerk.io verlässt sich im hohen Maße auf Bestellungen, um Ergebnisse vorherzusagen. Daher ist das Echtzeit-Tracking dieser Bestellungen zentral. Der Endpunkt log/sale wird hierfür verwendet.
Mit der Visitor-ID in diesem Aufruf versteht Clerk, welche Produkte angezeigt, angeklickt und schließlich gekauft wurden. Das ermöglicht es der KI, immer aktuell zu bleiben und die Ergebnisse dynamisch an das Kundenverhalten anzupassen.
Dieser Aufruf verknüpft außerdem die Visitor-ID mit der E-Mail-Adresse oder der Kunden-ID des Käufers und sorgt so für noch bessere Personalisierung durch kundenspezifische Empfehlungen.
Die Produkt-IDs sollten mit denen übereinstimmen, die auch für Klicks protokolliert werden. Bei konfigurierbaren Produkten sollten Sie z. B. immer die übergeordnete ID sowohl inlog/clickals auch inlog/saleerfassen, unabhängig davon, welche Variante gekauft wurde.
priceist der Stückpreis. Dieser wird in Analytics mitquantitymultipliziert.
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0",
"sale": 567,
"products": [
{
"id": 12793,
"price": 99.95,
"quantity": 2
},
{
"id": 1546,
"price": 14.00,
"quantity": 2
}
],
"customer": 1234,
"email": "theone@matrix.com",
"visitor": $_SESSION["clerk_visitor_id"]}' \
https://api.clerk.io/v2/log/sale
Diese Seite wurde von einer hilfreichen KI übersetzt, daher kann es zu Sprachfehlern kommen. Vielen Dank für Ihr Verständnis.