Beliebig (Webshop)

API

Synchronisierung von Daten #

Clerk synchronisiert jede Webshop-Domain, die als Store bezeichnet wird, als eigene Instanz, auf die über eine Reihe von API-Schlüsseln zugegriffen wird, die in der Clerk-Verwaltung zu finden sind:

Dazu gehören ein öffentlicher Schlüssel, der den Zugang zu Endpunkten ermöglicht, die nicht sensible Daten preisgeben, und ein privater Schlüssel. Der private Schlüssel ermöglicht Ihnen in Verbindung mit dem öffentlichen Schlüssel die Arbeit mit den Daten im Shop und den Zugriff auf sensible Daten wie Kunden- und Auftragsinformationen.

CRUD API #

Sie können Ihre Daten mit Hilfe der CRUD-API-Endpunkte synchronisieren, die es Ihnen ermöglichen, Ressourcen bei Bedarf zu erhalten, zu buchen, 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": "osLqDAs5s2tlf3adpLv6Mp1hxxf6GfdDuSE0c2ftT2ot5F3",
          "products":[
                {
                  "id": 123,
                  "name": "Green Lightsaber",
                  "description": "Antiuque rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Guaranteed idiot proof. "
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

Die verfügbaren Ressourcen sind:

Eines der Hauptunterscheidungsmerkmale von Clerk ist, dass es keine Lernphase gibt, da wir vom ersten Tag an alle vorhandenen Bestellungen nutzen können, um das aktuelle Kundenverhalten zu verstehen.

Dateneingabe #

Zusätzlich zur Verwendung der CRUD-API ist es sehr empfehlenswert, eine Backup-Synchronisationsmethode hinzuzufügen.

Schließlich können bei API-Aufrufen viele Dinge schief gehen. Zum Beispiel könnte Ihr Preisserver abstürzen oder ein Produktattribut könnte einen Fehler enthalten, der mehrere Aufrufe fehlschlagen lässt. Um diese Probleme zu vermeiden, sollten Sie einen Data Feed als tägliches Backup für Ihre CRUD-Aufrufe verwenden.

Der Feed ist eine JSON-Datei, die den aktuellen Stand des Katalogs eines Webshops enthält. Clerk arbeitet mit allen Daten, die zum Zeitpunkt des Ladens im Feed vorhanden sind, mit Ausnahme von Bestellungen, die protokolliert werden und nach dem ersten Import nicht mehr 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
  }
}

Der Datenfeed sollte unter einer URL verfügbar sein, auf die der Importer zugreifen kann, den Sie im Backend my.clerk.io konfigurieren:

Sie können den Feed sichern, so dass nur unser Importeur darauf zugreifen kann.

Abrufen von Daten #

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

Um beispielsweise die heißesten Produkte abzurufen, können Sie den Endpunkt “Empfehlungen/Trends” verwenden, und um die Top-Produkte für eine Suche nach “Star Wars” anzuzeigen, können Sie den Endpunkt “Suche/Prädiktion” verwenden.

Endpunkte #

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

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

Weitere Argumente hängen von dem Endpunkt ab, den Sie aufrufen. Für ergänzende Produkte ist beispielsweise eine Liste der Produkt-IDs erforderlich, um Zubehör zu finden, und für alle suchbezogenen Aufrufe ist der Parameter “query “ erforderlich, um Übereinstimmungen zu finden, usw.

Die notwendigen Argumente für alle Endpunkte finden Sie in unserer [API-Dokumentation] (https://docs.clerk.io/reference).

Standardmäßig gibt Clerks API alle verfügbaren Ergebnisse zurück, aber bei Bedarf kann mit Filters eine Teilmenge der Treffer definiert werden.

Empfehlungen Beispiel #

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

Suchbeispiel #

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

Visualisierung der Ergebnisse #

Die API von Clerk gibt bei der Rückgabe von Ergebnissen immer die IDs der gefundenen Treffer zurück.

// Call
curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 5,
          "labels": ["Homepage - Trending"]
        }'

// Response
{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693,
        12791,
        1546
    ],
    "count": 3902,
    "facets": null
}

Um Ihre Daten zu visualisieren, können Sie serverseitig API-Aufrufe tätigen, die IDs der übereinstimmenden Produkte abrufen und dann alle produktspezifischen Informationen von Ihrer Webshop-Plattform oder Ihrem PIM abrufen, bevor sie gerendert werden.

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-Cover-Bilder und mehr. Auf diese Weise müssen Sie oft keine einzelnen Aufrufe an Ihr PIM vornehmen, bevor Sie die Ergebnisse anzeigen, wodurch Ihre Seite schneller geladen wird.

// Call
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"],
          "attributes": ["id", "name", "price", "image", "url"]
        }'

// Response
{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693,
        12791,
        1546
    ],
    "count": 3902,
    "facets": null,
    "product_data": [
        {
            "id": 12793,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/2/8/2807199-baccarat-eye-small-oval-red-vase.jpg",
            "name": "Baccarat Eye Small Oval Red Vase",
            "price": 520.0,
            "url": "/"
        },
        {
            "id": 13827,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/1/t/1transatvj.jpg",
            "name": "Sabre Transat Garden Green 22cm Soup Spoon",
            "price": 13.96,
            "url": "/"
        },
        {
            "id": 12693,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/2/t/2transatdl.jpg",
            "name": "Sabre Transat Light Blue 22cm Dinner Fork",
            "price": 13.96,
            "url": "/"
        },
        {
            "id": 12791,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/1/8/1845244-baccarat-dom-perignon-champagne-flute-_set-of-2_.jpg",
            "name": "Baccarat Dom Perignon Champagne Flute (Set of 2)",
            "price": 260.0,
            "url": "/"
        },
        {
            "id": 1546,
            "image": "https://admin.davidshuttle.com/media/catalog/product/cache/2aecdb890d2a6ac64962b1f6d4fcec89/m/a/maison-berger-ocean-breeze-1-litre-lamp-refill.jpg",
            "name": "Maison Berger Ocean Breeze 1 Litre Lamp Refill",
            "price": 29.0,
            "url": "/"
        }
    ]
}

Aufspüren #

Schließlich muss das Tracking 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. Das Clerk-Tracking wird in 4 Schritten eingerichtet:

  1. Erzeugen einer [Sitzungs-ID für jeden Besucher] (https://docs.clerk.io/docs/visitor-tracking)
  2. Hinzufügen von beschreibenden Tracking-Labels zu API-Aufrufen, die Ergebnisse zurückliefern, die für die Anzeige von Analysen für einzelne Endpunkte verwendet werden
  3. Protokollierung der Klicks eines Besuchers auf von Clerk angezeigte Produkte
  4. Protokollierung jeder im Webshop getätigten Bestellung

Besucher (Session) ID #

Die Sitzungs-ID wird bei Clerk auch als Besucher-ID bezeichnet. Sie ist unbedingt erforderlich, um die Aktivitäten eines Benutzers während einer Sitzung im Webshop zu protokollieren, einschließlich angeklickter Produkte, durchgeführter Suchen und durchsuchter Kategorien. Diese Aktivität wird für jede Domain gespeichert und Clerk gibt sie niemals an andere Shops weiter.

Sie könnten zum Beispiel die PHP-Funktion uniqid() verwenden, um IDs zu erzeugen, die zumindest für die aktuelle Sitzung eindeutig sind. Nach der Generierung muss diese ID in allen Aufrufen von Clerk enthalten sein, damit die Verfolgung funktioniert.

<?php

session_start();

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

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Etiketten #

Labels müssen zu jedem Aufruf hinzugefügt werden, der Ergebnisse liefert, wie z. B. Suchergebnisse oder Alternativen auf einer Produktseite. Das Argument labels ist eine Liste, die mindestens eine Zeichenkette enthält, die das Label dieses Aufrufs sein sollte.

Es wird empfohlen, Labels zu verwenden, die die Seite, auf der der Aufruf verwendet wird, und die Art der angezeigten Ergebnisse enthalten, z. B. “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 #

Dann sollten Sie jeden Klick auf ein Clerk-Produkt mit log/click protokollieren. Es ist wichtig, nur diesen Aufruf zu machen, wenn das angeklickte Produkt tatsächlich von Clerk und nicht von der Webshop-Plattform selbst angezeigt wird; andernfalls sieht es so aus, als ob alle Produkte über Clerk gefunden werden.

Geben Sie die Produkt-ID “Produkt” an, und idealerweise auch den “API”-Endpunkt und die “Labels” aus dem API-Aufruf, der dieses Produkt angezeigt hat. Wenn dies nicht enthalten ist, wird Clerk den Klick zum letzten API-Aufruf zurückverfolgen, der dieses Produkt gezeigt hat.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --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
        }'

Protokollierung von Verkäufen #

Schließlich verwenden Sie log/sale, um jede Bestellung zu verfolgen, sobald sie im Webshop aufgegeben wird. Anhand der in diesem Aufruf enthaltenen Besucher-ID kann Clerk nachvollziehen, welche Produkte angezeigt, angeklickt und schließlich gekauft wurden. Auf diese Weise kann die KI immer auf dem neuesten Stand bleiben und die Ergebnisse je nach Kundenverhalten sofort ändern.

Wichtig:

  • Die “ID” der Produkte sollte mit den IDs übereinstimmen, die mit “log/click” protokolliert werden. Z.B. sollten Sie bei konfigurierbaren Produkten die ID der Eltern sowohl in log/click als auch in log/sale verfolgen, unabhängig von der gekauften Variante.
  • price” ist der Stückpreis für Produkte. Clerk multipliziert ihn mit der Menge in unserer Analyse.
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

Details der Besucher-ID #

Standardmäßig ist Clerk.io cookieless und verwendet anonyme Besucher-IDs, anstatt Cookies zu speichern.

Die ID wird für die Bereitstellung von Analysen in den Dashboards von Clerk.io und für Vor-Ort-Funktionen wie “Sie haben bereits besucht”-Empfehlungen verwendet.

Weitere Details über die Funktionsweise der Cookieless Personalisation finden Sie in diesem Artikel (http://help.clerk.io/de/platform/data/cookieless-solution/).

Wofür verwenden wir die ID? #

Dashboards, Analytik und Attribution.

Clerk.io verfolgt alle Bestellungen im Webshop und vergleicht die Bestellungen, die von Clerk.io beeinflusst werden, mit den Bestellungen, die nicht beeinflusst werden.

Über die Besucher-ID können wir nachverfolgen, wenn ein Kunde auf ein Produkt in einem Clerk.io-Element klickt und dann eine Bestellung aufgibt, die dieses Produkt enthält, um eine Zuordnung zu ermöglichen.

Vor-Ort-Funktionalität

Über die Besucher-ID erfassen wir die IDs der Produkte, die ein Verbraucher durchstöbert, und die von ihm durchgeführten Suchvorgänge.

Dies ermöglicht es uns, Empfehlungen im Webshop zu personalisieren, einschließlich Bannern wie " Unsere Empfehlungen für Sie” und " Sie haben zuvor gesehen”, die Produkte zeigen, die mit dem Browsen im Webshop zusammenhängen.

Die Besucher-ID und wie sie funktioniert #

Jeder Aufruf von Clerk.io enthält die oben beschriebene anonyme Besucher-ID, damit sie für die oben genannten Zwecke verwendet werden kann.

Wenn ein Besucher seine E-Mail-Adresse im Webshop angibt und/oder eine Bestellung aufgibt, wird die Besucher-ID mit seiner E-Mail-Adresse verknüpft, wenn sales-tracking aktiviert ist.

Eine E-Mail-Adresse in Clerk.io kann mehrere Besucher-IDs enthalten, die auf der Kundenseite in my.clerk.io zu sehen sind:

Wenn ein Benutzer Cookies von Ihrer Website akzeptiert, können Sie Clerk so konfigurieren, dass ein Cookie hinzugefügt wird, das eine langfristige Verfolgung mit dieser generierten ID ermöglicht. Dies geschieht einfach durch Hinzufügen von visitor: ‘persistent’ zu Clerk.js.

Deaktivieren der “Besucher”-ID #

Standardmäßig läuft Clerk.js im kochfreien Modus. Wenn also der Parameter Besucher nicht gesetzt ist, wird die Sitzungsaktivität aufgezeichnet, ohne dass ein Cookie hinzugefügt wird.

Wenn Sie dem Besucher die Möglichkeit geben möchten, nicht verfolgt zu werden, können Sie die ID durch Hinzufügen von ‘visitor’: null vollständig deaktivieren:

Clerk.js

Bei Konfigurationen, die Clerk.js verwenden, fügen Sie dies dem Clerk.js-Code für diesen Besucher hinzu:

API

Wenn Sie direkte API-Aufrufe verwenden, fügen Sie sie als Argument ein:

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "yu0tX54BcDAIuBp8RkNoldtcir9Dwip8",
          "limit": 30,
          "labels": ["Bestsellers"]
          "visitor": null}' \
     http://api.clerk.io/v2/recommendations/popular

Wenn Sie Fragen zum Besuchertracking haben, zögern Sie bitte nicht, sich über den Live-Chat in der unteren rechten Ecke an unser Customer Success Team zu wenden.