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 beschrieben sind. Sie müssen:

  1. Daten synchronisieren
  2. Ergebnisse abrufen
  3. Ergebnisse visualisieren
  4. 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 Zugriff auf Endpunkte mit nicht-sensiblen Daten gewährt, und einem Private Key, welcher das Arbeiten mit Daten des Stores und den Zugriff auf sensible Daten wie Kunden- und Bestellinformationen ermöglicht.

Private Keys können aus Sicherheitsgründen nur einmal nach der Erstellung angezeigt werden. Sie können beliebig viele für verschiedene Zwecke anlegen.

1. Daten synchronisieren #

Der erste Schritt ist, Daten einzugeben, damit die KI von Clerk.io Ihren Webshop versteht und Ergebnisse vorhersagen kann. Clerk synchronisiert jede Webshop-Domain als eigene Store-Instanz, auf die mit einem Satz von API-Schlüsseln zugegriffen wird.

CRUD API #

Sie können Ihre Daten mit den CRUD-API-Endpunkten synchronisieren, die es Ihnen ermöglichen, Ressourcen bedarfsgerecht 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 Unterscheidungsmerkmale von Clerk ist, dass es keine Lernphase gibt, da wir von Anfang an alle bestehenden Bestellungen nutzen können, um das aktuelle Kundenverhalten zu verstehen.

Data Feeds #

Zusätzlich zur Verwendung der CRUD API wird dringend empfohlen, eine Backup-Synchronisationsmethode hinzuzufügen. Es können schließlich viele Dinge mit API-Aufrufen schiefgehen.

Zum Beispiel könnte Ihr Preisserver abstürzen oder ein Produktattribut enthält einen Fehler, der mehrere Aufrufe fehlschlagen lässt. Um diese Probleme zu vermeiden, sollten Sie einen oder mehrere Data Feeds als tägliches Backup für Ihre CRUD-Aufrufe verwenden.

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

Alle im Feed zum Zeitpunkt des Ladens verfügbaren Daten sind diejenigen, mit denen Clerk arbeitet – mit Ausnahme von Bestellungen, die protokolliert und nach dem ersten Import nicht mehr Teil des Feeds sein müssen.

Die Verwendung des Data Feeds ist auch eine hervorragende Möglichkeit, Clerk mit Bestellungen vorzuladen.

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

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

Der/die Data Feed(s) sollte(n) unter einer URL verfügbar sein, die vom Importer abgerufen werden kann, den Sie im Backend von my.clerk.io unter System status > Data Sync. konfigurieren. Sie können den Feed absichern, damit nur unser Importer Zugriff darauf hat.

2. Daten abrufen #

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

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

Endpunkte #

Alle Endpunkte erfordern die Angabe des Public API Key.

Endpunkte, die Ergebnisse zurückgeben, benötigen zusätzlich das Argument “limit”, um die Anzahl der zurückgegebenen Ergebnisse zu steuern.

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

Die benötigten Argumente für alle Endpunkte finden Sie in unserer API-Dokumentation.

Standardmäßig gibt Clerk’s API alle verfügbaren Ergebnisse zurück, doch wenn nötig, können Filter eingesetzt werden, um eine Teilmenge von Treffern zu definieren.

Nachfolgend ein Beispiel für einen Aufruf eines Search-Endpunktes, 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-Endpunktes, 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 Reihenfolge zeigt, wie verschiedene Features die Ergebnisse beeinflusst haben. Jeder Eintrag enthält ein feature, eine menschenlesbare message, sowie strukturierte metadata, die die konkreten 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 #

Clerk’s API gibt immer die IDs der gefundenen Treffer zurück.

Um Ihre Daten zu visualisieren, können Sie serverseitige API-Aufrufe machen, die IDs der passenden Produkte abrufen und dann vor der Ausgabe alle produktbezogenen Informationen von Ihrer Webshop-Plattform oder Ihrem PIM einholen.

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
}

Clerk’s API kann auch so konfiguriert werden, dass sie alle ressourcenspezifischen Informationen zurücksendet, die Sie an Clerk senden, wie Preise, Markennamen, Kategorie-URLs, Blog-Cover-Bilder und mehr.

Damit müssen Sie oft keine einzelnen Aufrufe an Ihr PIM machen, 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, damit die KI von Clerk aktuell bleibt und die Ergebnisse für einen Besucher während seiner Sitzung personalisieren kann. Dafür sind 4 Schritte notwendig:

  1. Für jeden Besucher eine Sitzungs-ID generieren.
  2. Beschreibende Labels zu API-Aufrufen hinzufügen, die Ergebnisse liefern.
  3. Klicks eines Besuchers auf Produkte, die von Clerk angezeigt werden, protokollieren.
  4. Jede getätigte Bestellung im Webshop protokollieren.

Besucher-ID erstellen #

Die Sitzungs-ID wird auch als Visitor ID bezeichnet. Sie ist erforderlich, um die Aktivitäten eines Nutzers während einer Sitzung im Webshop zu protokollieren, einschließlich angeklickter Produkte, Suchen und besuchter Kategorien.

Diese Aktivität wird für jeden Store einzeln gespeichert und Clerk.io gibt sie nie zwischen Stores weiter.

Eine Visitor ID ist einfach ein String, der zur Identifizierung der Sitzung dient. Sie kann beliebige alphanumerische Zeichen enthalten, wobei wir für die beste Performance maximal 8 Zeichen empfehlen.

Beispielsweise können Sie mit PHPs uniqid()-Funktion IDs generieren, die mindestens für die aktuelle Sitzung 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, etwa Suchtreffer oder Alternativen auf einer Produktseite. Das Argument labels ist eine Liste mit mindestens einem String, der das beschreibende Label dieses Aufrufs ist.

Wir empfehlen die Verwendung von Labels, die die Seite beschreiben, auf der der Aufruf eingesetzt wird, sowie den Ergebnistyp. Ein Beispiel wäre Homepage - Trending. So lassen sie sich in der Analyse 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 #

Sie sollten jeden Klick auf ein Clerk.io-Produkt mit dem log/click-Endpunkt protokollieren.

Es ist wichtig, diesen Aufruf nur dann zu machen, wenn das geklickte Produkt tatsächlich von Clerk.io angezeigt wurde und nicht von der Webshop-Plattform selbst. Andernfalls erscheint es, als wären alle Produkte durch Clerk gefunden worden.

Der Aufruf sollte außerdem api enthalten, was der Endpunkt ist, über den das geklickte Produkt angezeigt wurde, und product, das die ID des geklickten Produkts enthält.

Search & Recommendations #

Das Protokollieren von Klicks erfolgt über das Hinzufügen der Parameter zum Aufruf auf Basis des genutzten Endpunktes. Dies ist einfach, da hier Daten aus Ihrer eigenen Implementierung genutzt werden.

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 von Clerk.io weitergeleiteten GET-Anfragen erhalten. Sie sollten darauf achten, ob die URL Parameter enthält, die belegen, 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. Dies sollte beim Protokollieren durch ein / ersetzt werden. external: 1 sollte dem Aufruf hinzugefügt werden, damit Clerk weiß, dass der Klick von einer E-Mail kommt.

Hier ein Beispiel für einen log/click-Aufruf mit den obigen 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 aufrufen, sollte dies protokolliert werden, um die Personalisierung von Ergebnissen zu ermöglichen, insbesondere von besucherbezogenen wie Visitor Recommendations oder Visitor Alternatives.

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

Wenn Sie diese jedoch nicht nutzen, müssen Sie einen separaten Aufruf an log/product machen und dabei die ID des betrachteten Produkts angeben.

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

E-Mail protokollieren #

Sobald die E-Mail-Adresse eines bekannten Kunden in der Sitzung verfügbar ist – egal ob er sich gerade eingeloggt oder bereits eingeloggt zurückkehrte – soll sie über den log/email-Endpunkt protokolliert werden.

Dies verknüpft die Visitor ID mit der E-Mail-Adresse, was Clerk.io benötigt, um automatisierte E-Mails auf Grundlage der Sitzungsaktivität auszulösen, Empfehlungen in E-Mails zu personalisieren und Merchandising-Kampagnen zuzuweisen, die auf bestimmte Audience-Segmente abzielen.

Ohne diesen Aufruf kann Clerk.io eine Sitzung nicht mit einer E-Mail-Adresse verknüpfen, es sei denn, der Besucher schließt einen Kauf ab.

Nehmen Sie diesen Aufruf einmal pro Sitzung vor, sobald die E-Mail verfügbar ist. Lassen Sie ihn für Gastbesuche vollständig weg:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/email' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}'

Verkäufe protokollieren #

Die KI von Clerk.io ist stark auf Bestellungen angewiesen, um Ergebnisse vorherzusagen. Daher ist das Echtzeit-Tracking von Bestellungen entscheidend. Der log/sale-Endpunkt wird hierfür genutzt.

Mit der Visitor ID in diesem Aufruf erkennt Clerk, welche Produkte gezeigt, angeklickt und schließlich gekauft wurden. Dadurch bleibt die KI immer aktuell und kann Ergebnisse in Echtzeit auf Basis des Kundenverhaltens anpassen.

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

Die id von Produkten sollte mit den IDs übereinstimmen, die für Klicks protokolliert werden. Z.B. bei konfigurierbaren Produkten sollten Sie immer die Eltern-ID in log/click und log/sale erfassen, egal welche Variante gekauft wurde.
price ist der Stückpreis. Er wird in der 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 während Spitzenzeiten Stabilität zu gewährleisten.

Die Limits sind:

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

Anfragen innerhalb dieser Limits werden nie von Rate Limiting betroffen sein. Anfragen, die diese Schwellen überschreiten, können dem Rate Limiting unterliegen; ob dies tatsächlich geschieht, hängt von der aktuellen Serverauslastung ab.

Clerk.io erweitert seine Infrastruktur dynamisch. Während stark frequentierter Events wie Black Friday werden zusätzliche Server gestartet, um den erhöhten Andrang zu bewältigen. Das heißt, die effektive Kapazität liegt deutlich über den Basis-Limits.

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