Jeder (Webshop)

API

Eine flexible Möglichkeit zur serverseitigen Integration.

Die gesamte 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, der es Ihnen ermöglicht, mit Store-Daten zu arbeiten und auf sensible Daten wie Kunden- und Bestellinformationen zuzugreifen.

Private Keys können aus Sicherheitsgründen nur einmal nach der Erstellung eingesehen werden, und Sie können so viele davon erstellen, wie Sie für verschiedene Zwecke benötigen.

1. Daten synchronisieren #

Der erste Schritt besteht darin, Daten einzugeben, damit die AI von Clerk.io Ihren Webshop versteht und Ergebnisse vorhersagen kann. Clerk synchronisiert jede Webshop-Domain als eine eigene Store-Instanz, auf die mit einem Satz von API Keys zugegriffen wird.

CRUD API #

Sie können Ihre Daten über die CRUD API-Endpunkte synchronisieren, die Ihnen ermöglichen, Ressourcen auf Abruf zu abrufen, hinzuzufügen, zu aktualisieren und zu 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 bei Clerk ist, dass es keine Lernphase gibt, da wir ab Tag eins alle vorhandenen Bestellungen nutzen können, um das aktuelle Kundenverhalten zu verstehen.

Datenfeeds #

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

Zum Beispiel kann Ihr Preisserver abstürzen oder ein Produktattribut kann einen Fehler enthalten, 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.

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

Alle Daten, die beim Laden im Feed verfügbar sind, sind die, mit denen Clerk arbeitet – mit Ausnahme von Bestellungen, die protokolliert werden und nach dem ersten Import nicht in den Feed aufgenommen werden 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 Datenfeed(s) sollten über eine URL verfügbar sein, die vom Importer erreicht werden kann; diese konfigurieren Sie im Backend von my.clerk.io unter System status > Data Sync. Sie können den Feed absichern, damit nur unser Importer darauf zugreifen kann.

2. Daten abrufen #

Sobald die Daten synchronisiert sind, analysiert die AI sie und erstellt intelligente Indizes, die je nach Anwendungsfall über eindeutige Endpunkte abgerufen werden können.

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

Endpunkte #

Alle Endpunkte erfordern die Angabe des public API key.

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

Zusätzliche Parameter hängen vom aufgerufenen Endpunkt ab. Z. B. benötigen die besten Alternativen products, eine Liste von Produkt-IDs, für die Accessoires gefunden werden sollen, und alle suchbezogenen Aufrufe benötigen den Parameter query, um Übereinstimmungen 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, aber falls nötig, können Filter verwendet werden, um eine Teilmenge der Treffer zu definieren.

Nachfolgend finden Sie ein Beispiel, wie Sie einen Aufruf an einen Search-Endpunkt machen, um die Top-Produkte zu einer 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 finden Sie 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"]
        }'

Antwort-Debugging #

Wenn das Debugging für eine Anfrage aktiviert ist, enthalten API-Antworten ein debug-Array, das in der Reihenfolge anzeigt, wie unterschiedliche Features die Ergebnisse beeinflusst haben. Jeder Eintrag enthält ein feature, eine menschlich lesbare message und 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 #

Clerks API gibt immer die IDs der Übereinstimmungen zurück, die gefunden wurden.

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 darstellen.

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
}

Clerks API kann auch so konfiguriert werden, dass sie jede produktspezifische Information zurücksendet, die Sie an Clerk übermitteln, wie etwa Preise, Markennamen, Kategorie-URLs, Blog-Titelbilder und mehr.

Dadurch müssen Sie häufig keine einzelnen Aufrufe an Ihr PIM vor der Anzeige von Ergebnissen machen, 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 AI von Clerk auf dem neuesten Stand bleibt und die Ergebnisse für einen Besucher während der Sitzung personalisiert werden können. Dies umfasst 4 Schritte:

  1. Erzeugen einer Session-ID für jeden Besucher.
  2. Hinzufügen beschreibender Labels zu API-Aufrufen, die Ergebnisse zurückgeben.
  3. Protokollieren der Klicks eines Besuchers auf Produkte, die von Clerk angezeigt werden.
  4. Protokollieren jeder Bestellung, die im Webshop aufgegeben wird.

Visitor-ID erstellen #

Die Session-ID wird auch Visitor ID genannt. 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äten werden für jeden Store gespeichert, und Clerk.io teilt sie niemals zwischen Stores.

Eine Visitor-ID ist lediglich eine Zeichenkette, mit der die Sitzung identifiziert wird. Sie kann beliebige alphanumerische Zeichen enthalten, und wir empfehlen eine maximale Länge von 8 Zeichen für die beste Performance.

Sie können beispielsweise mit PHPs uniqid()-Funktion IDs erzeugen, die mindestens für die aktuelle Sitzung eindeutig sind. Nach der Generierung muss diese ID bei allen Aufrufen an die Clerk.io-API angegeben werden, damit das Tracking funktioniert.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Labels hinzufügen #

Labels müssen allen Aufrufen hinzugefügt werden, die Ergebnisse zurückgeben, wie z. B. Suchtreffer oder Alternativen auf einer Produktseite. Das Argument labels ist eine Liste, die mindestens einen String enthalten muss – das beschreibende Label dieses Aufrufs.

Wir empfehlen Labels zu verwenden, die die Seite beschreiben, auf der der Aufruf genutzt wird, und die Art der Ergebnisse, die sie anzeigen. Ein Beispiel wäre Homepage - Trending. So können sie in Analytics leicht unterschieden werden.

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 über den log/click-Endpunkt protokollieren.

Es ist wichtig, diesen Aufruf nur dann zu machen, wenn das angeklickte Produkt wirklich von Clerk.io und nicht vom Webshop selbst angezeigt wurde. Andernfalls sieht es so aus, als ob alle Produkte über Clerk gefunden werden.

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

Search & Recommendations #

Das Protokollieren von Klicks erfolgt durch Hinzufügen der Parameter zum Aufruf, basierend auf dem Endpunkt, der zur Anzeige des Produkts verwendet wurde. Dies ist unkompliziert, da dafür die Daten aus Ihrem eigenen Setup 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 #

Hier funktioniert das Protokollieren von Klicks anders, da Sie die Daten aus GET-Anfragen erhalten, die von Clerk.io weitergeleitet werden. Sie sollten überprüfen, ob die URL Parameter enthält, die darauf hinweisen, dass Besucher von einer Email Recommendation auf die Produktseite kommen.

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; ist dies der Fall, sollte der Klick mit den erhaltenen Daten protokolliert werden.

clerk_api enthält den API-Endpunkt mit einem *, um Codierungsprobleme zu vermeiden. Dieser 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 Email stammt.

Hier ist 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 ansehen, sollte dies protokolliert werden, damit Ergebnisse personalisiert werden können – insbesondere die besucherbezogenen wie Visitor Recommendations oder Visitor Alternatives.

Wenn Sie einen Endpunkt nutzen, der bereits die Angabe der Produkt-ID erfordert, wie recommendations/substituting oder recommendations/complementary, wird die Produkt-ID automatisch von Clerk.io protokolliert.

Wenn Sie diese nicht nutzen, müssen Sie einen separaten Aufruf an log/product mit der ID des betrachteten Produkts machen.

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 AI von Clerk.io stützt sich stark auf Bestellungen, um Ergebnisse vorherzusagen. Das Tracking dieser Bestellungen in Echtzeit ist daher entscheidend. Dafür wird der Endpunkt log/sale verwendet.

Mit der Übermittlung der Visitor ID in diesem Aufruf versteht Clerk, welche Produkte angezeigt, angeklickt und letztlich gekauft wurden. So kann die AI stets aktuell bleiben und Ergebnisse dynamisch anpassen.

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

Die id der Produkte sollte mit den IDs übereinstimmen, die für Klicks protokolliert werden. Für konfigurierbare Produkte sollten Sie bei log/click und log/sale immer die Parent-ID tracken – unabhängig von der gekauften Variante.
price ist der Stückpreis. Er wird in Analytics mit 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

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