Jeder (Webshop)

API

Eine flexible Möglichkeit zur serverseitigen Integration.

Die gesamte Kommunikation mit Clerk erfolgt über die API:

https://api.clerk.io/v2

Für die Einrichtung dieser Kommunikation sind 4 Schritte erforderlich, die in dieser Anleitung beschrieben werden. Sie müssen:

  1. Daten synchronisieren
  2. Ergebnisse abrufen
  3. Die Ergebnisse visualisieren
  4. Tracking hinzufügen

API-Schlüssel #

Diese Schlüssel werden verwendet, um auf die Daten Ihres Shops zuzugreifen. Sie befinden sich in my.clerk.io > Developers > API Keys.

Sie bestehen aus einem öffentlichen Schlüssel, der Zugriff auf Endpunkte mit nicht sensiblen Daten gewährt, und einem privaten Schlüssel, der es Ihnen erlaubt, mit den Daten im Store zu arbeiten und auf sensible Daten wie Kunden- und Bestellinformationen zuzugreifen.

Private Schlüssel können aus Sicherheitsgründen nur einmal nach der Erstellung angezeigt werden, und Sie können so viele 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 ihre eigene eindeutige 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 abrufen, erstellen, aktualisieren und löschen bedarfsgerecht.

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

Datenfeeds #

Zusätzlich zur Verwendung der CRUD-API wird dringend empfohlen, eine Backup-Synchronisierungsmethode hinzuzufügen. Schließlich kann bei API-Aufrufen vieles schiefgehen.

Zum Beispiel könnte Ihr Preisserver abstürzen oder ein Produktattribut könnte einen Fehler enthalten, der mehrere Aufrufe zum Scheitern bringt. Um diese Probleme zu vermeiden, sollten Sie einen oder mehrere Data Feeds 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 Daten, die im Feed zum Zeitpunkt des Ladevorgangs verfügbar sind, werden von Clerk verwendet – mit Ausnahme von Bestellungen, die protokolliert werden und nach dem ersten Import nicht im Feed enthalten sein müssen.

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

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

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

Der oder die Datenfeeds sollten unter einer URL verfügbar sein, die vom Importer aufgerufen werden 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 darauf zugreifen kann.

2. Daten abrufen #

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

Um beispielsweise die beliebtesten Produkte abzurufen, verwenden Sie den Endpunkt recommendations/trending, und um die Top-Produkte einer Suche nach “star wars” anzuzeigen, verwenden Sie den Endpunkt search/predictive.

Endpunkte #

Für alle Endpunkte müssen Sie den öffentlichen API-Schlüssel übermitteln.

Endpunkte, die Ergebnisse zurückgeben, erfordern außerdem das Argument " limit", um die Anzahl der zurückgegebenen Ergebnisse zu steuern.

Weitere Parameter hängen vom aufgerufenen Endpunkt ab. Beispielsweise benötigen die besten Alternativen das Argument products, eine Liste von Produkt-IDs, für die Zubehör gefunden werden soll. Suchbezogene Aufrufe benötigen den Parameter query, um Übereinstimmungen zu finden.

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

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

Unten finden 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 #

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

Antwort-Debugging #

Wenn das Debugging für eine Anfrage aktiviert ist, enthalten API-Antworten ein debug-Array, das nacheinander zeigt, 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 API von Clerk gibt bei der Rückgabe von Ergebnissen immer die IDs der gefundenen Übereinstimmungen zurück.

Um Ihre Daten zu visualisieren, können Sie API-Aufrufe serverseitig durchführen, die IDs der passenden Produkte abrufen und dann alle produktspezifischen Informationen von Ihrer Webshop-Plattform oder Ihrem PIM abrufen, bevor Sie diese 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 API von Clerk kann auch so konfiguriert werden, dass sie jede ressourcenspezifische Information zurückgibt, die Sie an Clerk übermitteln, wie Preise, Markennamen, Kategorie-URLs, Blog-Titelbilder und mehr.

Dadurch müssen Sie häufig keine Einzelanfragen an Ihr PIM stellen, bevor Sie Ergebnisse anzeigen, was Ihre Seite schneller laden lässt.

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 #

Tracking muss hinzugefügt werden, um die KI von Clerk aktuell zu halten und die Ergebnisse für einen Besucher während seiner Sitzung zu personalisieren. Das erfordert 4 Schritte:

  1. Für jeden Besucher eine Sitzungs-ID generieren.
  2. Beschreibende Labels zu API-Aufrufen hinzufügen, die Ergebnisse zurückgeben.
  3. Die Klicks eines Besuchers auf von Clerk angezeigte Produkte protokollieren.
  4. Jede Bestellung im Webshop protokollieren.

Visitor-ID erstellen #

Die Sitzungs-ID wird auch als Visitor ID bezeichnet. Sie ist erforderlich, um die Aktivitäten eines Nutzers während einer Sitzung auf dem Webshop zu protokollieren, einschließlich der Produkte, auf die er klickt, seiner Suchanfragen und der von ihm besuchten Kategorien.

Diese Aktivität wird für jeden Store gespeichert, und Clerk.io gibt sie nie über verschiedene Stores hinweg weiter.

Eine Visitor ID ist einfach ein String, mit dem die Sitzung identifiziert wird. Sie kann beliebige alphanumerische Zeichen enthalten; wir empfehlen eine maximale Länge von 8 Zeichen für die beste Leistung.

Zum Beispiel können Sie mit der PHP-Funktion uniqid() IDs generieren, die für mindestens die laufende Sitzung eindeutig sind. Nach der Generierung muss diese ID in allen Aufrufen an die API von Clerk.io 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 bei allen Aufrufen hinzugefügt werden, die Ergebnisse zurückgeben, wie Suchtreffer oder Alternativen auf einer Produktseite. Das labels-Argument ist eine Liste mit mindestens einem String, der das beschreibende Label für diesen Aufruf sein sollte.

Wir empfehlen, Labels zu verwenden, die die Seite beschreiben, auf der der Aufruf verwendet wird, sowie den Typ der Ergebnisse, die angezeigt werden. Ein Beispiel wäre Homepage - Trending. Damit lassen sie sich in der Auswertung leicht 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 #

Jeder Klick auf ein Clerk.io-Produkt sollte mit dem Endpunkt log/click protokolliert werden.

Es ist wichtig, diesen Aufruf nur dann auszuführen, wenn das angeklickte Produkt tatsächlich von Clerk.io angezeigt wurde und nicht von der Webshop-Plattform selbst. Andernfalls sieht es so aus, als ob alle Produkte über Clerk gefunden werden.

Der Aufruf sollte auch das Feld api enthalten, also den Endpunkt, der verwendet wurde, um das angeklickte Produkt anzuzeigen. Zudem muss product die ID des angeklickten Produkts enthalten.

Search & Recommendations #

Das Protokollieren von Klicks erfolgt durch die Übergabe der Parameter basierend auf dem Endpunkt, der zum Anzeigen des Produkts verwendet wurde. Dies ist unkompliziert, da Sie die Daten aus Ihrer eigenen Integration 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 #

Das Protokollieren von Klicks funktioniert hier anders, da Sie die Daten aus GET-Anfragen erhalten, die von Clerk.io weitergeleitet werden. Sie sollten überwachen, ob die URL Parameter enthält, die darauf hinweisen, 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 Encoding-Probleme zu vermeiden. Dies sollte beim Protokollieren des Klicks in / geändert werden. external: 1 sollte dem Aufruf hinzugefügt werden, damit Clerk erkennt, dass der Klick aus einer Email stammt.

Hier ist ein Beispiel für einen log/click-Aufruf mit den oben genannten Daten:

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 anschauen, 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 eine Produkt-ID benötigen, wie recommendations/substituting oder recommendations/complementary, protokolliert Clerk.io die Produkt-ID automatisch.

Falls Sie diese nicht verwenden, müssen Sie einen separaten Aufruf zu 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 ist stark auf Bestellungen angewiesen, um Ergebnisse vorherzusagen, deshalb ist das Tracking dieser Daten in Echtzeit entscheidend. Dafür wird der Endpunkt log/sale verwendet.

Mit der Visitor ID in diesem Aufruf versteht Clerk, welche Produkte angezeigt, angeklickt und letztlich gekauft wurden. So kann die KI immer auf dem neuesten Stand bleiben und Ergebnisse in Echtzeit an das Kundenverhalten anpassen.

Dieser Aufruf verknüpft außerdem die Visitor ID mit der E-Mail-Adresse oder der Kunden-ID des Käufers, was durch kundenspezifische Empfehlungen eine noch bessere Personalisierung ermöglicht.

Die id der Produkte sollte mit den IDs übereinstimmen, die für Klicks protokolliert werden. Bei konfigurierbaren Produkten sollten Sie beispielsweise die Parent-ID sowohl in log/click als auch in log/sale verfolgen, unabhängig von der gekauften Variante.
price ist der Stückpreis. Er wird in den Analysen 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 während hoher Lastphasen zu gewährleisten.

Die Limits sind:

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

Anfragen innerhalb dieser Limits werden niemals limitiert. Anfragen, die diese Schwellenwerte überschreiten, können limitiert werden – ob dies tatsächlich geschieht, hängt jedoch von der aktuellen Serverkapazität ab.

Clerk.io skaliert seine Infrastruktur dynamisch. Während verkehrsintensiver Ereignisse wie Black Friday werden zusätzliche Server bereitgestellt und sind aktiv, um das erhöhte Aufkommen zu bewältigen, was bedeutet, dass die tatsächliche Kapazität deutlich höher als die angegebenen Basis-Limits sein kann.

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