Jeder (Webshop)

API

Eine flexible Möglichkeit zur serverseitigen Integration.

Alle Kommunikation mit Clerk erfolgt über die API:

https://api.clerk.io/v2

Die Einrichtung dieser Kommunikation erfordert 4 Schritte, die in diesem Leitfaden erläutert werden. 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 Stores zuzugreifen. Sie finden sie in my.clerk.io > Developers > API Keys.

Sie bestehen aus einem Public Key, der den Zugriff auf Endpunkte mit nicht-sensiblen Daten gewährt, und einem Private Key, der Ihnen erlaubt, mit Daten im Store zu arbeiten und auf sensible Daten wie Kunden- und Bestelldaten zuzugreifen.

Private Keys können aus Sicherheitsgründen nach ihrer Erstellung nur einmal angezeigt werden, und Sie können beliebig viele für verschiedene Zwecke erstellen.

1. Daten synchronisieren #

Der erste Schritt besteht darin, Daten einzuspielen, sodass die KI von Clerk.io Ihren Webshop versteht und Ergebnisse vorhersagen kann. Clerk synchronisiert jede Webshop-Domain als eigene, einzigartige Store-Instanz, auf die über ein Set von API Keys zugegriffen wird.

CRUD API #

Sie können Ihre Daten mithilfe der CRUD API-Endpunkte synchronisieren, die es Ihnen ermöglichen, Ressourcen bei Bedarf zu abrufen (get), erstellen (post), aktualisieren (update) und löschen (delete).

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 Hauptunterschiede von Clerk besteht darin, dass es keine Lernphase gibt, da wir ab dem ersten Tag alle bestehenden Bestellungen nutzen können, um das aktuelle Kundenverhalten zu verstehen.

Datenfeeds #

Zusätzlich zur Nutzung der CRUD API wird dringend empfohlen, eine Backup-Synchronisierungsmethode hinzuzufügen. Es kann schließlich viel schiefgehen bei API-Aufrufen.

Zum Beispiel könnte Ihr Preisserver abstürzen oder ein Produktattribut könnte einen Fehler enthalten, der dazu führt, dass mehrere Aufrufe fehlschlagen. Um diese Probleme zu vermeiden, sollten Sie einen oder mehrere Data Feeds als tägliche Sicherung für Ihre CRUD-Aufrufe verwenden.

Datenfeeds sind eine oder mehrere JSON-Dateien, die den aktuellen Katalog des Webshops enthalten.

Alle Daten, die beim Laden im Feed verfügbar sind, sind die Daten, mit denen Clerk arbeitet – mit Ausnahme von Bestellungen, diese werden protokolliert und müssen nach dem ersten Import nicht mehr im Feed enthalten sein.

Die Nutzung des Datenfeeds ist auch eine hervorragende Möglichkeit, Clerk mit Bestellungen vorzubeladen.

{
  "products": [ ... ],
  "categories": [ ... ],
  "orders": [ ... ],
  "customers": [ ... ],
  "pages": [ ... ],

  "config": {
    "created": 1567069830,
    "strict": false
  }
}

Die Datenfeeds sollten unter einer URL verfügbar sein, die vom Importer erreicht werden kann. Diese konfigurieren Sie im my.clerk.io Backend unter System status > Data Sync. Sie können den Feed absichern, sodass nur unser Importer darauf zugreifen kann.

2. Daten abrufen #

Sobald Daten synchronisiert sind, analysiert die KI diese und erstellt intelligente Indizes, die über individuelle Endpunkte je nach Anwendungsfall abgerufen werden können.

Zum Beispiel können Sie, um die angesagtesten Produkte abzurufen, den Endpunkt recommendations/trending verwenden. Um die Top-Produkte für eine Suche nach “star wars” anzuzeigen, können Sie den Endpunkt search/predictive verwenden.

Endpunkte #

Alle Endpunkte verlangen, dass Sie den öffentlichen API-Schlüssel senden.

Endpunkte, die Ergebnisse zurückgeben, benötigen außerdem das Argument “limit” zur Steuerung der Anzahl der zurückgegebenen Ergebnisse.

Weitere Parameter hängen vom jeweiligen Endpunkt ab. Zum Beispiel benötigen die besten Alternativen products, eine Liste von Produkt-IDs, zu denen Zubehör gefunden werden soll, und alle suchbezogenen Aufrufe benötigen den Parameter query, um Übereinstimmungen zu finden.

Sie finden die erforderlichen Argumente für alle Endpunkte in unserer API-Dokumentation.

Standardmäßig gibt die Clerk API alle verfügbaren Ergebnisse zurück, aber falls nötig, können Filter verwendet werden, um eine Teilmenge der Ergebnisse zu definieren.

Search #

Nachfolgend ein Beispiel für einen Aufruf an einen Search-Endpunkt, 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 an einen Recommendations-Endpunkt, 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 beim Request das Debugging aktiviert ist, enthalten API-Antworten ein debug-Array, das in der Reihenfolge anzeigt, wie verschiedene Funktionen die Ergebnisse beeinflusst haben. Jeder Eintrag enthält ein feature, eine lesbare message und strukturierte metadata, die die jeweiligen Effekte beschreibt.

{
  "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 beim Zurückgeben von Ergebnissen immer die IDs der gefundenen Treffer zurück.

Um Ihre Daten zu visualisieren, können Sie serverseitig API-Aufrufe ausführen, die IDs der passenden Produkte abrufen und dann alle produktspezifischen Informationen von Ihrer Webshop-Plattform oder Ihrem PIM beziehen, bevor Sie diese anzeigen.

Call

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"]
        }'

Response

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null
}

Die Clerk API kann auch so konfiguriert werden, dass sie jede ressourcenspezifische Information, die Sie an Clerk senden – wie Preise, Markennamen, Kategorie-URLs, Blog-Coverbilder und mehr – zurücksendet.

Damit müssen Sie oftmals keine Einzelanfragen an Ihr PIM stellen, bevor Sie Ergebnisse anzeigen – das beschleunigt das Laden Ihrer Seite.

Call

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"]
        }'

Response

{
    "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 #

Tracking muss hinzugefügt werden, damit Clerk’s KI sich laufend aktualisiert und die Ergebnisse eines Besuchers während der Session personalisieren kann. Dafür sind 4 Schritte erforderlich:

Generieren Sie eine Session-ID für jeden Besucher.
Fügen Sie beschreibende Labels zu API-Aufrufen hinzu, die Ergebnisse zurückgeben.
Protokollieren Sie Klicks eines Besuchers auf Produkte, die von Clerk angezeigt werden.
Protokollieren Sie jede Bestellung, die im Webshop getätigt wird.

Besucher-ID erstellen #

Die Session-ID wird auch als Besucher-ID bezeichnet. Sie wird benötigt, um die Aktivitäten eines Nutzers während einer Session im Webshop zu protokollieren, einschließlich Produkte, auf die er klickt, seine Suchanfragen und Kategorien, die er durchsucht.

Diese Aktivität wird für jeden Store gespeichert, und Clerk.io gibt diese niemals Store-übergreifend weiter.

Eine Besucher-ID ist einfach eine Zeichenkette zur Identifizierung der Session. Es können beliebige alphanumerische Zeichen sein; zu optimalen Performance empfehlen wir, sie auf maximal 8 Zeichen zu beschränken.

Zum Beispiel können Sie mit der PHP-Funktion uniqid() IDs generieren, die zumindest für die aktuelle Session eindeutig sind. Nach der Generierung muss diese ID in allen Aufrufen an die Clerk.io-API enthalten sein, damit das Tracking funktioniert.

<?php

session_start();

$current_visitor = uniqid(); //Beispiel: "646f1f0584371"

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Labels hinzufügen #

Labels müssen zu allen Aufrufen hinzugefügt werden, die Ergebnisse zurückgeben, wie Suchergebnisse oder Alternativen auf einer Produktseite. Das Argument labels ist eine Liste mit mindestens einem String, der das beschreibende Label dieses Aufrufs sein sollte.

Wir empfehlen, Labels zu verwenden, die die Seite beschreiben, wo der Aufruf verwendet wird, und die Art der Ergebnisse, die angezeigt werden. Ein Beispiel könnte Homepage - Trending sein. Dadurch sind sie in den Analysen leicht zu unterscheiden.

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.

Es ist wichtig, diesen Aufruf nur auszuführen, wenn das geklickte Produkt tatsächlich von Clerk.io angezeigt wurde, nicht von der Webshop-Plattform selbst. Andernfalls würde es so aussehen, als ob alle Produkte über Clerk gefunden wurden.

Der Aufruf sollte außerdem api enthalten, also den verwendeten Endpunkt für das geklickte Produkt, und product, die ID des geklickten Produkts.

Search & Recommendations #

Das Protokollieren der Klicks geschieht durch Hinzufügen der Parameter zum Aufruf, basierend auf dem Endpunkt, über den das Produkt angezeigt wurde. Dies ist einfach, da Sie dafür die Daten Ihrer eigenen Einrichtung verwenden.

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 #

Hier läuft das Protokollieren der Klicks anders ab, da Sie die Daten aus GET-Anfragen erhalten, die von Clerk.io weitergeleitet werden. Sie sollten prüfen, ob die URL Parameter enthält, die anzeigen, dass Besucher über eine Email Recommendation auf einer Produktseite landen.

Diese Anfragen enthalten stets die folgenden 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 * statt /, um Kodierungsprobleme zu vermeiden. Dies sollte beim Protokollieren des Klicks in / geändert werden. external: 1 sollte dem Aufruf hinzugefügt werden, damit Clerk weiß, dass der Klick aus einer E-Mail kommt.

Hier ein Beispielaufruf für log/click, der die oben genannten Daten verwendet:

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 auch dies protokolliert werden, um die Ergebnisse zu personalisieren – insbesondere besucherbezogene wie Besucherempfehlungen oder -alternativen.

Wenn Sie Endpunkte nutzen, die ohnehin die Produkt-ID benötigen, wie recommendations/substituting oder recommendations/complementary, protokolliert Clerk.io die Produkt-ID automatisch.

Falls sie dies nicht tun, müssen Sie einen separaten Aufruf an log/product machen, mit der ID des betrachteten 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 stark auf Bestellungen, um Ergebnisse vorherzusagen, daher ist deren Tracking in Echtzeit entscheidend. Der Endpunkt log/sale wird hierzu verwendet.

Wird die Besucher-ID in diesem Aufruf übergeben, kann Clerk verstehen, welche Produkte angezeigt, angeklickt und schließlich gekauft wurden. So bleibt die KI immer aktuell und kann Ergebnisse laufend an das Kundenverhalten anpassen.

Dieser Aufruf verknüpft außerdem die Besucher-ID mit der E-Mail-Adresse oder Customer ID des Käufers und ermöglicht so eine noch bessere Personalisierung über kundenbezogene Recommendations.

Die id der Produkte sollten mit den IDs übereinstimmen, die für Klicks protokolliert werden. Zum Beispiel sollten Sie bei konfigurierbaren Produkten immer die Eltern-ID sowohl in log/click als auch in log/sale tracken, unabhängig davon, welche Variante gekauft wurde.

price ist der Stückpreis. Er wird in den Analytics mit der quantity multipliziert.

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

Rate Limiting #

Die API verwendet Rate Limiting, um eine faire Nutzung sicherzustellen und die Stabilität bei Spitzenlasten zu wahren.

Die Limits sind:

50 Anfragen pro Sekunde pro Store
100 Anfragen pro Sekunde pro IP-Adresse

Anfragen innerhalb dieser Limits werden nie rate-limitiert. Anfragen, die diese Schwellenwerte überschreiten, können rate-limitiert werden, wobei dies von der aktuellen Serverkapazität abhängt.

Clerk.io skaliert seine Infrastruktur dynamisch. Während stark frequentierter Ereignisse wie Black Friday werden mehr Server bereitgestellt, um die erhöhte Last zu bewältigen – das bedeutet, die effektive Kapazität ist dann deutlich höher als die Basislimits vermuten lassen.

Diese Seite wurde von einer hilfreichen KI übersetzt, daher kann es zu Sprachfehlern kommen. Vielen Dank für Ihr Verständnis.