Any (webshop)

API

Eine flexible Möglichkeit, serverseitig zu integrieren.

Alle Kommunikation mit Clerk erfolgt über die API:

https://api.clerk.io/v2

Die Einrichtung dieser Kommunikation erfordert 4 Schritte, die in diesem Leitfaden dargelegt sind. 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 finden sie in my.clerk.io > Einstellungen > API-Schlüssel.

Sie bestehen aus einem Öffentlichen Schlüssel, der Zugriff auf Endpunkte gewährt, die nicht sensible Daten offenlegen, und einem Privaten Schlüssel, der es Ihnen ermöglicht, mit Daten im Shop 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 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 einzigartige Shop-Instanz, die über ein Set von API-Schlüsseln aufgerufen wird.

CRUD API #

Sie können Ihre Daten mithilfe der CRUD API-Endpunkte synchronisieren, die es Ihnen ermöglichen, Ressourcen nach Bedarf abzurufen, 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": "Grünes Lichtschwert",
                  "description": "Antikes Rebellenlichtschwert.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Narrensicher."
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

Die verfügbaren Objekte sind:

Eines der Hauptunterscheidungsmerkmale von Clerk ist, 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 Preiserver 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 in Betracht ziehen, einen oder mehrere Datenfeeds als tägliche Sicherung für Ihre CRUD-Aufrufe zu verwenden.

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

Alle Daten, die im Feed verfügbar sind, wenn er geladen wird, werden von Clerk verwendet, mit Ausnahme von Bestellungen, die protokolliert werden und nach dem ersten Import nicht im Feed enthalten sein müssen.

Die Verwendung des Datenfeeds ist auch eine großartige Möglichkeit, Clerk mit Bestellungen vorzuladen.

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

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

Die Datenfeed(s) sollten unter einer URL verfügbar sein, die vom Importeur aufgerufen werden kann, die Sie im my.clerk.io Backend in Systemstatus > Datensynchronisierung. konfigurieren. Sie können den Feed sichern, sodass nur unser Importeur darauf zugreifen kann.

2. Daten abrufen #

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

Zum Beispiel, um die heißesten Produkte abzurufen, können Sie den Endpunkt recommendations/trending verwenden, und um die Top-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 senden.

Endpunkte, die Ergebnisse zurückgeben, erfordern auch das Argument " limit", um die Anzahl der zurückzugebenden Ergebnisse zu steuern.

Zusätzliche Parameter hängen vom aufgerufenen Endpunkt ab. Zum Beispiel erfordern 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 Übereinstimmungen zu finden.

Die erforderlichen 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 falls erforderlich, können Filter verwendet werden, um eine Teilmenge von Übereinstimmungen zu definieren.

Suche #

Nachfolgend ein Beispiel für einen Aufruf eines Suchendpunkts, um die besten 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": ["Suche - Vorhersage"]
        }'

Empfehlungen #

Nachfolgend ein Beispiel für einen Aufruf eines Empfehlungsendpunkts, um die heißesten 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"]
        }'

3. Ergebnisse visualisieren #

Die API von Clerk gibt immer die IDs der Übereinstimmungen zurück, die sie bei der Rückgabe von Ergebnissen gefunden hat.

Um Ihre Daten zu visualisieren, können Sie API-Aufrufe serverseitig durchführen, die IDs der übereinstimmenden Produkte abrufen und dann alle produktspezifischen Informationen von Ihrer Webshop-Plattform oder 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 API von Clerk kann auch so konfiguriert werden, dass sie alle ressourcenspezifischen Informationen zurücksendet, die Sie an Clerk senden, wie Preise, Markennamen, Kategorie-URLs, Blog-Coverbilder und mehr.

Damit müssen Sie oft keine einzelnen Aufrufe an Ihr PIM tätigen, bevor Sie Ergebnisse anzeigen, was Ihre Seite schneller lädt.

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 auf dem neuesten Stand zu halten und die Ergebnisse eines Besuchers während seiner Sitzung zu personalisieren. Es erfordert 4 Schritte:

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

Erstellen Sie eine Besucher-ID #

Die Sitzungs-ID wird auch als Besucher-ID bezeichnet. Sie ist erforderlich, um die Aktivitäten eines Benutzers während einer Sitzung im Webshop zu protokollieren, einschließlich der Produkte, auf die sie klicken, ihrer Suchen und der Kategorien, die sie durchsuchen.

Diese Aktivitäten werden für jeden Shop gespeichert, und Clerk.io teilt sie niemals zwischen den Shops.

Eine Besucher-ID ist einfach eine Zeichenfolge, die verwendet wird, um die Sitzung zu identifizieren. Sie kann aus beliebigen alphanumerischen Zeichen bestehen, und wir empfehlen, sie auf maximal 8 Zeichen zu beschränken, um die beste Leistung zu erzielen.

Zum Beispiel könnten Sie die PHP-Funktion uniqid() verwenden, um IDs zu generieren, die mindestens für die aktuelle Sitzung einzigartig sind. Nach der Generierung muss diese ID in allen Aufrufen zur 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 zu allen Aufrufen hinzugefügt werden, die Ergebnisse zurückgeben, wie z. B. Suchübereinstimmungen oder Alternativen auf einer Produktseite. Das Argument labels ist eine Liste, die mindestens einen String enthalten sollte, der das beschreibende Label dieses Aufrufs sein sollte.

Wir empfehlen, Labels zu verwenden, die die Seite beschreiben, auf der der Aufruf verwendet wird, und die Art der Ergebnisse, die sie anzeigen. Ein Beispiel könnte Homepage - Trending sein. Dies macht sie in der Analyse 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 Produkt von Clerk.io mit dem log/click Endpunkt protokollieren.

Es ist wichtig, diesen Aufruf nur zu machen, wenn das angeklickte Produkt tatsächlich von Clerk.io und nicht von der Webshop-Plattform selbst angezeigt wird. Andernfalls wird es so aussehen, als ob alle Produkte über Clerk gefunden wurden.

Der Aufruf sollte auch das api enthalten, welches der Endpunkt ist, der verwendet wurde, um das angeklickte Produkt anzuzeigen, und product, das die ID des angeklickten Produkts enthält.

Suche & Empfehlungen #

Das Protokollieren von Klicks erfolgt, indem die Parameter zum Aufruf basierend auf dem Endpunkt hinzugefügt werden, der verwendet wurde, um das angeklickte Produkt anzuzeigen. Dies ist unkompliziert, da es Daten aus der Einrichtung verwendet, die Sie selbst vorgenommen 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
        }'

E-Mail-Empfehlungen #

Das Protokollieren von Klicks funktioniert anders, da Sie die Daten von GET-Anfragen erhalten, die von Clerk.io weitergeleitet werden. Sie sollten überwachen, ob die URL Parameter enthält, die darauf hinweisen, dass Besucher auf einer Produktseite von einer E-Mail-Empfehlung landen.

Diese Anfragen enthalten immer die folgenden Abfrageparameter:

{
  "utm_source": "clerk",
  "utm_medium": "email",
  "utm_campaign": "Willkommens-E-Mail - Bestseller",
  "utm_content": "clerk-recommendations",
  "clerk_product": 12793,
  "clerk_labels": "Willkommens-E-Mail - Bestseller",
  "clerk_api": "recommendations/popular",
  "clerk_n": 0,
  "clerk_external": 1
}

Wir empfehlen, zu überwachen, ob die URL clerk_external: 1 enthält, und wenn ja, protokollieren Sie den Klick mit den Daten, die Sie erhalten.

clerk_api enthält den API-Endpunkt mit einem *-Zeichen, 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 stammt.

Hier ist ein Beispiel für einen log/click-Aufruf, der die obigen 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": ["Willkommens-E-Mail - Bestseller"],
          "api": "recommendations/popular",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793,
          "external": 1
        }'

Produkte protokollieren #

Wenn Besucher Produktseiten anzeigen, sollte dies protokolliert werden, damit es zur Personalisierung von Ergebnissen verwendet werden kann - insbesondere der besucherbezogenen Ergebnisse wie Besucherempfehlungen oder Besucheralternativen.

Wenn Sie Endpunkte verwenden, die bereits die Produkt-ID benötigen, um zu funktionieren, wie recommendations/substituting oder recommendations/complementary, protokolliert Clerk.io die Produkt-ID automatisch.

Wenn Sie diese jedoch nicht verwenden, müssen Sie einen separaten Aufruf an log/product mit der ID des angesehenen Produkts vornehmen.

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, daher ist es entscheidend, diese in Echtzeit zu verfolgen. Der log/sale Endpunkt wird dafür verwendet.

Mit der in diesem Aufruf enthaltenen Besucher-ID versteht Clerk, welche Produkte angezeigt, angeklickt und schließlich gekauft wurden. Dies ermöglicht es der KI, immer auf dem neuesten Stand zu bleiben und die Ergebnisse basierend auf dem Kundenverhalten in Echtzeit zu ändern.

Dieser Aufruf verknüpft auch die Besucher-ID mit der E-Mail-Adresse oder Kunden-ID des Käufers, 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. Zum Beispiel sollten Sie bei konfigurierbaren Produkten die ID der Eltern sowohl in log/click als auch in log/sale unabhängig von der gekauften Variante verfolgen.
price ist der Einheitspreis. Er wird in der Analyse 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.