Data Feeds

Übersicht #

Unabhängig von Ihrer E-Commerce-Plattform und davon, ob wir eine Integration haben oder nicht, können Sie Daten jederzeit mit Clerk.io über einen oder mehrere Feeds im JSON-Format synchronisieren.

Wir unterstützen zwei verschiedene Varianten der Feeds:

• Mehrere Dateien für verschiedene Objekte
• Eine einzelne Datei, die alle Objekte enthält

Die beiden Lösungen verwenden dieselbe Objektstruktur, bieten jedoch verschiedene Möglichkeiten zur Absicherung und zum Import, die in diesem Leitfaden erläutert werden.

Alle Objekttypen außer Bestellungen werden aus den Feeds in die Clerk.io-Datenbank gespiegelt. Wenn Sie ein Objekt aus dem Feed entfernen, entfernt Clerk.io es beim Import aus der Datenbank. Bestellungen werden protokolliert und in der Datenbank behalten.

Wir empfehlen, den/die JSON-Feed(s) mindestens einmal täglich zu generieren, idealerweise jedoch öfter. Sie können auch bei Bedarf generiert werden, wenn der Importer von Clerk.io sie anfordert.

Die Feed(s) sollten unter einer URL verfügbar sein, die von den Servern von Clerk.io erreichbar ist.

https://your-website.com/json-feed.json

Datentypen #

Wir unterstützen Attribute der Typen: int, float, str, array, bool, dict (object).

Null-Werte #

Nicht geprüfte null-Werte führen mit der Zeit garantiert zu Fehlern. Wenn ein Attribut für ein bestimmtes Produkt, eine Kategorie oder eine Bestellung nicht existiert, lassen Sie das Attribut einfach weg.

ID-Werttypen #

Wir empfehlen dringend, Ganzzahlen als IDs zu verwenden, aber es ist auch möglich, Strings zu verwenden. Sie müssen sich jedoch immer auf einen Typ im Feed festlegen, d. h. alle IDs Ihrer Objekte müssen vom selben Typ sein.

Attributnamen #

Objektattribute dürfen nur alphanumerische Werte (A-Z, 0-9) und Unterstriche enthalten.
Ein gültiger Attributname könnte also brand_name sein, aber nicht läbel-mærke.

Die Verwendung von Bindestrichen oder Sonderzeichen im Attributnamen führt dazu, dass sie beim Sync ignoriert werden.

Objektstruktur #

JSON-Feeds bestehen aus einer Liste von Objekten mit verschiedenen Feldern, die deren Daten ausmachen.

Objekte müssen mindestens die erforderlichen Felder für den jeweiligen Typ enthalten, damit die KI von Clerk.io korrekt funktioniert. Sie können optional weitere Attribute enthalten, die in der E-Commerce-Plattform verfügbar sind.

Produkte #

Jedes Objekt repräsentiert ein einzelnes Produkt. Wenn Sie konfigurierbare Produkte haben, empfehlen wir, nur das Eltern-Produkt zu senden und Attribute wie color, size, material usw. zur Beschreibung der Varianten beizufügen.

Nachfolgend finden Sie die erforderlichen Felder und Beispiele für optionale, die häufig in Onlineshops verwendet werden.

Beispiel JSON #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 79995.95,
    "list_price": 99995.95,
    "on_sale": true,
    "image": "https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
    "url": "https://galactic-empire-merch.com/antique-rebel-lightsaber",
    "brand": "Je'daii",
    "categories": [987, 654],
    "created_at": 1199145600,
    "color": {
      "name": "Emerald",
      "converted_name": "Green",
      "image": "https://galactic-empire-merch.com/images/a-r-lightsaber-emerald.jpg",
      "color_code": "#7CFC00"
    },
    "reviews_amount": 164,
    "reviews_avg": 4.8
  },
  {
    "id": 261,
    "name": "Death Star Deluxe",
    "description": "Death Star - Guaranteed idiot proof",
    "price": 99999999999999.95,
    "list_price": 99999999999999.95,
    "on_sale": false,
    "image": "https://galactic-empire-merch.com/images/death-star.jpg",
    "url": "https://galactic-empire-merch.com/death-star",
    "brand": "Imperial Inc.",
    "categories": [345678],
    "created_at": 1197565600
  }
]

Produkte behalten ohne Indexierung #

Für einige Setups möchten Sie vielleicht Produkte in der Datenbank von Clerk.io behalten, ohne sie jemals in Suchergebnissen anzuzeigen.

Wenn Sie Tickets oder gebrauchte Artikel verkaufen, die nur zeitweise verfügbar sind und danach verschwinden, ist es sinnvoll, die Historie dieser Produkte zu erhalten, damit Clerk diese Daten zur Verbesserung der Ergebnisse nutzen kann.

Fügen Sie dafür das spezielle Attribut index: false zu den Produktobjekten hinzu, die erhalten bleiben, aber nicht indiziert werden sollen. Clerk wird dann die Verkaufshistorie zur Ergebnisberechnung nutzen, aber sie nie in API-Antworten anzeigen.

Für andere Produkte lassen Sie das Attribut einfach weg oder setzen Sie es auf index: true.

Kategorien #

Jedes Objekt stellt eine einzelne Kategorie dar. Clerk.io baut eine interne Kategoriebäume anhand der für jede Kategorie angegebenen Unterkategorien auf.

Nachfolgend finden Sie die erforderlichen Felder und Beispiele für optionale, die häufig in Onlineshops verwendet werden.

Beispiel JSON #

[
  {
    "id": 1,
    "name": "Imperial Goods",
    "subcategories": [42, 25],
    "url": "https://galactic-empire-merch.com/imperial-goods"
  },
  {
    "id": 42,
    "name": "Tatooine",
    "subcategories": [],
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine"
  },
  {
    "id": 25,
    "name": "Coruscant",
    "subcategories": [],
    "url": "https://galactic-empire-merch.com/imperial-goods/coruscant"
  }
]

Bestellungen #

Bestellungen werden protokolliert und beim Entfernen aus dem Feed nicht gelöscht. Sie müssen im Allgemeinen nur beim ersten Import gesendet werden und können danach entfernt werden, um Serverkapazität zu sparen. Sie können über unsere CRUD API gelöscht werden.

parcels Daten können aktuell nur über die CRUD API synchronisiert werden. Die Dokumentation finden Sie hier.

Jedes Objekt steht für eine einzelne Bestellung. Clerk.io verwendet die Produkt-IDs und E-Mail-Adresse/Kunden-ID in Bestellungen, um das Kundenverhalten zu analysieren und Trends zu erkennen. Zusammen mit products ist dies der wichtigste Objekttyp.

Nachfolgend finden Sie die erforderlichen und optionalen Felder. Es ist nicht möglich, zusätzliche Attribute für Bestellungen zu senden.

Beispiel JSON #

[
  {
    "id": 123458,
    "customer": 789,
    "email": "vader@the-death-star.com",
    "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00}],
    "time": 1389871120
 },
  {
    "id": 123456,
    "customer": 456,
    "email": "obi.wan@kenobi.me",
    "products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00},{"id":123,"quantity":2,"price":60.00}],
    "time": 1389870977
 },
  {
    "id": 123457,
    "customer": "",
    "products": [{"id":789,"quantity":2,"price":120.00}],
    "time": 1389871090
 }
]

Kunden #

Jedes Objekt stellt einen einzelnen Kunden dar. Die bereitgestellten Attribute werden dann mit der email oder der Kunden-ID aus Bestellungen zusammengeführt, um ein Kundenprofil für die Nutzung mit Audience zu erstellen.

Nachfolgend finden Sie die erforderlichen Felder und Beispiele für optionale, die häufig in Onlineshops verwendet werden.

Beispiel JSON #

[
  {
    "id": 135,
    "name": "Luke Skywalker",
    "email": "luke@rebels.com",
    "subscribed": true,
    "gender": "male",
    "zip": "1134",
    "is_b2b": "false"
 },
  {
    "id": 165,
    "name": "Leia Organa",
    "email": "leia@royalty.org",
    "subscribed": false,
    "gender": "female",
    "age": 19,
    "interests": ["politics", "outlaws"],
    "is_b2b": true
 }
]

Seiten #

Jedes Objekt steht für eine einzelne Seite. Seiten sind generell alle Arten von E-Commerce-Inhalten, die nicht als Produkt oder Kategorie klassifiziert sind. Dies können Artikel, Blog-Posts, Landingpages, Marken-Seiten oder andere Textinhalte sein.

Nachfolgend finden Sie die erforderlichen Felder und Beispiele für optionale, die häufig in Onlineshops verwendet werden.

Beispiel JSON #

[
  {
    "id": 135,
    "type": "cms",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Open Hours",
    "text": "The main text about our opening hours..."
 },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "New Blog Post",
    "text": "The main text about our opening hours...",
    "keywords": ["blog", "post", "new"]
 }
]

Mehrsprachigkeit #

Clerk.io funktioniert am besten, wenn Sie für jede Sprache einen eigenen Store anlegen. Jeder Store kann auf die Sprache des Inhalts eingestellt werden, wodurch Search Grammatik und Rechtschreibfehler viel besser versteht.

Zudem haben Kunden aus verschiedenen Regionen oft unterschiedliche Vorlieben und Suchmuster, weshalb es am besten ist, die Bestelldaten ebenfalls in verschiedene Stores zu trennen.

Alternativ können Sie mehrsprachige JSON-Feeds erstellen, in denen alle Textattribute als Objekte mit Sprachcodes als Schlüssel und deren Übersetzungen als Wert vorliegen.

Alle Textattribute müssen Sprachschlüssel erhalten, auch wenn der Inhalt identisch ist, damit sie für die Sprache durchsuchbar sind.

Bei API-Aufrufen geben Sie den Parameter language sowie den passenden Sprachschlüssel an, um die korrekten Daten abzurufen.

Beispiel Mehrsprachiger JSON #

[
  {
    "id": 135,
    "name": {
      "english":"Lightsaber",
      "spanish":"Sable de luz", 
      "italian":"Spada laser"
      },
    "description": {
      "english":"Antique Rebel Lightsaber",
      "spanish":"Sable de luz rebelde antiguo",
      "italian":"Antica spada laser ribelle"
      },
    "price": 99995.95,
    "image": {
      "english":"https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
      "spanish":"https://galactic-empire-merch.com/es/images/a-r-lightsaber.jpg",
      "italian":"https://galactic-empire-merch.com/it/images/a-r-lightsaber.jpg"
      },
    "url": {
      "english":"https://galactic-empire-merch.com/antique-rebel-lightsaber",
      "spanish":"https://galactic-empire-merch.com/es/antique-rebel-lightsaber",
      "italian":"https://galactic-empire-merch.com/it/antique-rebel-lightsaber"
      },
    "brand": "Je'daii",
    "categories": [987, 654],
    "created_at": 1199145600,
    "color": {
      "name": "Emerald",
      "converted_name": "Green",
      "image": "https://galactic-empire-merch.com/images/a-r-lightsaber-emerald.jpg",
      "color_code": "#7CFC00"
    },
    "reviews_amount": 164,
    "reviews_avg": 4.8
 },
  {
    "id": 261,
    "name": {
      "english":"Death Star Deluxe",
      "spanish":"Estrella de la Muerte de lujo", 
      "italian":"La Morte Nera Deluxe"
      },
    "description": {
      "english":"Death Star - Guaranteed idiot proof",
      "spanish":"Estrella de la Muerte: a prueba de idiotas garantizada",
      "italian":"Morte Nera - A prova di idiota garantita"
      },
    "price": 99999999999999.95,
    "image": {
      "english":"https://galactic-empire-merch.com/images/death-star.jpg",
      "spanish":"https://galactic-empire-merch.com/es/images/death-star.jpg",
      "italian":"https://galactic-empire-merch.com/it/images/death-star.jpg"
      },
    "url": {
      "english":"https://galactic-empire-merch.com/death-star",
      "spanish":"https://galactic-empire-merch.com/es/death-star",
      "italian":"https://galactic-empire-merch.com/it/death-star"
      },
    "brand": "Imperial Inc.",
    "categories": [345678],
    "created_at": 1197565600
 }
]

Beispiel-Aufruf #

curl -X GET \
  https://api.clerk.io/v2/recommendations/popular \
  -H 'Content-Type: application/json' \
  -d 'key=your_store_public_key&limit=10&language=italian'

Unterstützte Sprachen #

Die Sprache muss mit ihrem genauen Namen angegeben werden. Aktuell unterstützen wir 54 Sprachen. Sollte Ihre Sprache nicht unten aufgeführt sein, wählen Sie eine verwandte Sprache oder einfach „english“. Es funktioniert trotzdem, aber die Grammatikneutralisierung in Search ist dann weniger effektiv.

• afrikaans
• albanian
• arabic
• armenian
• azerbaijani
• basque
• belarusian
• bengali
• bosnian
• bulgarian
• catalan
• chinese
• croatian
• czech
• danish
• dutch
• english
• estonian
• finnish
• french
• galician
• georgian
• german
• greek
• hebrew
• hindi
• hungarian
• icelandic
• indonesian
• irish
• italian
• japanese
• korean
• latvian
• lithuanian
• macedonian
• malay
• norwegian
• persian
• polish
• portuguese
• romanian
• russian
• serbian
• slovak
• slovenian
• spanish
• swedish
• filipino
• thai
• turkish
• ukrainian
• urdu
• vietnamese

Mehrere Feeds #

Dies ist der empfohlene Ansatz, da es effizient für Ihren Server ist und das höchste Maß an Kontrolle bietet.

Bei diesem Ansatz erstellen Sie einzelne Feed-Dateien für jedes Ihrer Objekte. Dies nutzt die Sync-Methode Clerk.io JSON Feed V2.

Diese unterstützen content-type: application/x-ndjson oder application/json.

Jeder Feed sollte ein Array von Objekten enthalten.

URL #

https://awsumstuff.com/feed/products.json

Ausgabe #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 99995.95,
 },
  ...
]

Paginierung #

Dies ist ein optionales Feature, das es Ihnen erlaubt, die Ergebnisse zu paginieren, indem Ihr Feed die folgenden Query-Parameter akzeptiert:

• limit: Die Anzahl der Objekte pro Seite.
• offset: Der Index des ersten Objekts pro Seite.

Der Importer von Clerk.io kann so konfiguriert werden, dass er diese Parameter an Ihren Feed sendet. Sie müssen nur auswählen, wie viele Objekte Sie pro Seite abrufen möchten.

Wenn Sie Ihre Feed-URL konfigurieren, können Sie dann {{limit}} und {{offset}} verwenden, um die Parameter anzuhängen.

{{limit}} enthält die Zahl, die Sie in den Importeinstellungen festlegen. {{offset}} beginnt beim ersten Aufruf bei 0 und wächst fortlaufend je nach limit.

Zum Beispiel:

• Aufruf 1: limit=100&offset=0
• Aufruf 2: limit=100&offset=100
• Aufruf 3: limit=100&offset=200

Die Abbruchbedingung ist, wenn Ihr Feed ein leeres Array zurückgibt.

URL #

https://awsumstuff.com/feed/products.json?limit={{limit}}&offset={{offset}}

Inkremente #

Die Nutzung dieses Features bedeutet, dass Clerk.io beim Import keine Objekte mehr löscht. Sie müssen also CRUD-API-Aufrufe verwenden, um Objekte aus der Clerk.io-Datenbank zu entfernen.

Die Multi-Feed-Lösung unterstützt das optionale Feature, nur Daten zu schicken, die sich innerhalb einer gewählten Anzahl von Tagen geändert haben, anstatt jedes Mal alle Daten zu senden.

Dazu konfigurieren Sie Ihren Feed so, dass er nur Objekte ausgibt, die im angegebenen Zeitraum verändert wurden, wenn der Parameter modified_after gesetzt ist.

Dann geben Sie im Feld Incremental time {{modified_after}} in den Clerk.io-Importeinstellungen die Anzahl der Tage an.

Dadurch behält Clerk.io alle Daten in der Datenbank und aktualisiert nur die Objekte, die im Feed enthalten sind.

Um die konfigurierte Tagesanzahl zu verwenden, fügen Sie den Query-Parameter modified_after zu Ihrer Feed-URL hinzu und integrieren Sie das Tag, das Ihre angegebene Anzahl von Tagen einfügt. Zum Beispiel:

https://awsumstuff.com/feed/products.json?modified_after={{modified_after}}&limit={{limit}}&offset={{offset}}

Sicherheit #

Wir empfehlen, dass der JSON-Feed nur verschlüsselte SSL-Verbindungen akzeptiert und nach Möglichkeit HTTP-Authentifizierung verwendet.

Zusätzlich können Sie in den Importeinstellungen Token Authentication aktivieren. Clerk.io sendet dann bei jedem HTTP-Request einen Authorization Header, den Sie prüfen, bevor Sie Daten ausliefern:

X-Clerk-Authorization: Bearer THE_TOKEN

Das Token können Sie mit einem POST-Request an den token/verify-Endpunkt überprüfen:

curl -X POST \
  https://api.clerk.io/v2/token/verify \
  -H 'Content-Type: application/json' \
  -d '{"token": "THE_TOKEN", "key": "your_store_public_key"}'

Einzelner Feed #

Parameter #

Neben den Objekten selbst unterstützt dieser Ansatz zwei zusätzliche Parameter:

• created: Ein Unix-Timestamp, wann der Feed zuletzt aktualisiert wurde. Der Importer von Clerk.io erkennt damit, ob neue Daten abgerufen werden sollen.
• strict: Bei true werden alle Daten exakt wie geliefert importiert. Bei false versucht Clerk.io, die Daten zu bereinigen, z. B. durch Entfernen doppelter Produkte oder Kategorien sowie Konvertierungen von als String hinterlegten Zahlen in Int/Float.

Beispiel-Feed #

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

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

Sicherheit #

Ihre Daten sind äußerst geschäftskritisch, daher hat Sicherheit oberste Priorität!

Wir empfehlen, dass der JSON-Feed nur verschlüsselte SSL-Verbindungen akzeptiert und nach Möglichkeit HTTP-Authentifizierung verwendet.

Zusätzlich bietet Clerk eine weitere Sicherheitsebene, um zu bestätigen, dass die Feed-Anfrage von einer vertrauenswürdigen Quelle (also uns) stammt.

Das System basiert auf einem gemeinsamen Geheimnis; einem Private API Key, den Sie in my.clerk.io unter Developers > API Keys anlegen können.

Alle Clerk.io-Anfragen via HTTP oder HTTPS enthalten zwei Query-Parameter hash und salt.

salt ist eine zufällige Zeichenkette zum Salzen der Hash-Funktion, und hash ist ein SHA512-Hash, berechnet aus dem Private API Key folgendermaßen:

hash = SHA512(salt + private_key + str(int(floor(unix_timestamp() / 100))))

Ein Beispiel-Request kann wie folgt aussehen:

https://example.com/clerk-product-feed.php?salt=f4Ke...A02X&hash=4DFF...340F

Indem Sie von der Anfrage beide Parameter salt und hash abfragen und mit dem Private Key denselben Hash auf Ihrem Server berechnen, können Sie die Werte vergleichen und so bestätigen, dass die Anfrage von Clerk.io stammt.