Jeder (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 beschrieben 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 angesehen 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 über die 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 #

Neben der Verwendung der CRUD API wird dringend empfohlen, eine Backup-Synchronisationsmethode 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ägliches Backup für Ihre CRUD-Aufrufe zu verwenden.

Datenfeeds sind eine oder mehrere JSON-Dateien, die den aktuellen Katalog der 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 Backend von my.clerk.io in Systemstatus > Datensynchronisation. 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 besten 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, für die 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 API von Clerk alle verfügbaren Ergebnisse zurück, aber wenn nötig, können Filter verwendet werden, um eine Teilmenge von Übereinstimmungen zu definieren.

Suche #

Im Folgenden finden Sie 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 #

Im Folgenden finden Sie 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": ["Startseite - 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": ["Startseite - 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": ["Startseite - 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 von Clerk angezeigte Produkte.
  4. Protokollieren Sie jede Bestellung, die im Webshop aufgegeben 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 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 Erstellung 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 Startseite - Trending sein. Dies macht sie in der Analyse leicht unterscheidbar.

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": ["Startseite - 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 tätigen, 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 die api enthalten, die 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 zu dem Aufruf hinzugefügt werden, basierend auf dem Endpunkt, der verwendet wurde, um das angeklickte Produkt anzuzeigen. Dies ist unkompliziert, da es Daten aus der von Ihnen selbst vorgenommenen Einrichtung 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": ["Startseite - 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, den Klick mit den Daten zu protokollieren, 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 wie Besucherempfehlungen oder Besucheralternativen.

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

Wenn Sie diese jedoch nicht verwenden, müssen Sie einen separaten Aufruf an log/product mit der ID des durchsuchten Produkts tätigen.

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 für konfigurierbare Produkte die ID der Eltern in sowohl log/click als auch log/sale verfolgen, unabhängig von der gekauften Variante.
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.