Data Feeds

Übersicht #

Unabhängig von Ihrer eCommerce-Plattform und ob wir eine Integration haben oder nicht, können Sie Daten immer 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 die gleiche Objektstruktur, haben jedoch verschiedene Funktionen zur Sicherung und zum Import, die in diesem Leitfaden beschrieben sind.

Alle Objekttypen außer Bestellungen werden von den Feeds in die Datenbank von Clerk.io gespiegelt. Wenn Sie ein Objekt aus dem Feed entfernen, wird Clerk.io es aus der Datenbank entfernen, wenn es importiert wird. Bestellungen werden protokolliert und in der Datenbank gespeichert.

Wir empfehlen, die JSON-Feed(s) mindestens einmal täglich zu generieren, idealerweise jedoch häufiger. Sie können auch auf Anfrage 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 aus zugänglich ist.

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

Datentypen #

Wir unterstützen Attribute der Typen: int, float, str, array, bool.

Null-Werte #

Ungeprüfte null-Werte sind ein sicherer Weg, um im Laufe der Zeit Fehler einzuschleichen. 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, es ist jedoch auch möglich, Strings zu verwenden. Sie müssen sich immer auf 1 Typ in Ihrem Feed festlegen, was bedeutet, dass alle IDs für Ihre Objekte vom gleichen Typ sein müssen.

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 in den Attributnamen führt dazu, dass sie in der Synchronisation ignoriert werden.

Objekte Struktur #

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

Objekte müssen mindestens die erforderlichen Felder für den Typ enthalten, damit die KI von Clerk.io ordnungsgemäß funktioniert, und optional können sie zusätzliche Attribute enthalten, die in der eCommerce-Plattform verfügbar sind.

Produkte #

Jedes Objekt repräsentiert ein einzelnes Produkt. Wenn Sie konfigurierbare Produkte haben, empfehlen wir, nur das übergeordnete Produkt zu senden und Attribute einzuschließen, die die Kinder beschreiben, wie color, size, material usw.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, die häufig von eCommerce-Shops verwendet werden.

Beispiel JSON #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antike Rebellen-Lichtschwert",
    "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_names": ["Kohle","Rubin","Smaragd"],
    "color_names_converted": ["Schwarz","Rot","Grün"],
    "color_codes": ["#7CFC00","#FF3131"],
    "reviews_amount": 164,
    "reviews_avg": 4.8
  },
  {
    "id": 261,
    "name": "Death Star Deluxe",
    "description": "Todesstern - Garantiert idiotensicher",
    "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 ohne Indizierung beibehalten #

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

Wenn Sie Tickets oder gebrauchte Artikel verkaufen, die für eine Zeit verfügbar sind, bevor sie nie wiederkommen, ist es eine gute Idee, die Historie dieser Produkte intakt zu halten, damit Clerk sie zur Verbesserung der Ergebnisse verwenden kann.

Um dies zu tun, fügen Sie das spezielle Attribut index: false zu den Produktobjekten hinzu, die ohne Indizierung beibehalten werden sollen. Clerk wird dann die Historie ihrer Verkäufe verwenden, um Ergebnisse anzuzeigen, aber sie werden niemals in API-Aufrufen angezeigt.

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

Kategorien #

Jedes Objekt repräsentiert eine einzelne Kategorie. Clerk.io erstellt einen internen Kategorienbaum basierend auf den bereitgestellten Unterkategorien für jede Kategorie.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, die häufig von eCommerce-Shops verwendet werden.

Beispiel JSON #

[
  {
    "id": 1,
    "name": "Imperiale Waren",
    "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 werden nicht gelöscht, wenn sie aus dem Feed entfernt werden. Sie müssen im Allgemeinen nur während des ersten Imports gesendet werden und können dann wieder entfernt werden, um Serverkapazität zu sparen. Sie können über unsere CRUD API gelöscht werden.

parcels-Daten können derzeit nur über die CRUD-API synchronisiert werden. Überprüfen Sie die Dokumentation hier.

Jedes Objekt repräsentiert eine einzelne Bestellung. Clerk.io verwendet die Produkt-IDs und die E-Mail-Adresse/Kunden-ID innerhalb von Bestellungen, um das Kundenverhalten zu analysieren und Trends zu identifizieren. Zusammen mit products ist es der wichtigste Objekttyp.

Unten sehen Sie die erforderlichen Felder und optionale 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 repräsentiert einen einzelnen Kunden. Die bereitgestellten Attribute werden dann mit der email oder der customer ID des Kunden aus Bestellungen zusammengeführt, um ein einzelnes Kundenprofil für die Verwendung mit Audience Segmentierung zu erstellen.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, die häufig von eCommerce-Shops verwendet werden.

Beispiel JSON #

[
  {
    "id": 135,
    "name": "Luke Skywalker",
    "email": "luke@rebels.com",
    "subscribed": true,
    "gender": "männlich",
    "zip": "1134",
    "is_b2b": "false"
 },
  {
    "id": 165,
    "name": "Leia Organa",
    "email": "leia@royalty.org",
    "subscribed": false,
    "gender": "weiblich",
    "age": 19,
    "interests": ["Politik", "Gesetzesbrecher"],
    "is_b2b": true
 }
]

Seiten #

Jedes Objekt repräsentiert eine einzelne Seite. Seiten sind im Allgemeinen alle Arten von eCommerce-Inhalten, die nicht als Produkt oder Kategorie klassifiziert sind. Es könnte sich um Artikel, Blogbeiträge, Landingpages, Markenseiten und andere Arten von schriftlichem Inhalt handeln.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, die häufig von eCommerce-Shops verwendet werden.

Beispiel JSON #

[
  {
    "id": 135,
    "type": "cms",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Öffnungszeiten",
    "text": "Der Haupttext über unsere Öffnungszeiten..."
 },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Neuer Blogbeitrag",
    "text": "Der Haupttext über unsere Öffnungszeiten...",
    "keywords": ["blog", "beitrag", "neu"]
 }
]

Mehrsprachigkeit #

Clerk.io funktioniert am besten, wenn Sie separate Stores für jede Sprache erstellen. Jeder Store kann mit der Sprache des Inhalts konfiguriert werden, was es der Suche ermöglicht, Grammatik- und Rechtschreibfehler viel besser zu verstehen.

Darüber hinaus haben Kunden aus verschiedenen Regionen oder Ländern tendenziell unterschiedliche Vorlieben und Suchmuster, was bedeutet, dass es am besten funktioniert, die Bestelldaten in verschiedene Stores zu unterteilen.

Eine Alternative dazu ist der Aufbau von mehrsprachigen JSON-Feeds, bei denen alle Textattribute als Objekte mit Sprachcodes als Schlüsseln und ihren Übersetzungen als Werten bereitgestellt werden.

Alle Textattribute müssen Sprachschlüssel haben, auch wenn der Inhalt darin derselbe ist, um sicherzustellen, dass sie für die Sprache durchsuchbar sind.

Bei API-Aufrufen fügen Sie den Parameter language und den passenden Sprachschlüssel hinzu, um die richtigen 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_names": ["Green","Red"],
    "color_codes": ["#7CFC00","#FF3131"],
    "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
 }
]

Beispielaufruf #

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. Wenn Ihre Sprache nicht auf der folgenden Liste steht, wählen Sie eine Sprache mit demselben Stamm oder einfach “english”. Es wird immer noch funktionieren, aber die Grammatikneutralisation in der Suche wird weniger effektiv sein.

• dänisch
• niederländisch
• englisch
• finnisch
• französisch
• deutsch
• italienisch
• norwegisch
• portugiesisch
• russisch
• spanisch
• schwedisch

Mehrere Feeds #

Dies ist der empfohlene Ansatz, da er effizient für Ihren Server ist und den höchsten Grad an Kontrolle bietet.

Mit diesem Ansatz erstellen Sie einzelne Feed-Dateien für jedes Ihrer Objekte. Dies verwendet die Synchronisationsmethode namens 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": "Antike Rebellen-Lichtschwert",
    "price": 99995.95,
 },
  ...
]

Pagination #

Dies ist eine optionale Funktion, die es Ihnen ermöglicht, Ergebnisse zu paginieren, indem Sie Ihren Feed so codieren, dass er die folgenden Abfrageparameter akzeptiert:

• limit: Die Anzahl der Objekte, die pro Seite zurückgegeben werden sollen.
• offset: Der Index des ersten Objekts, das auf einer Seite zurückgegeben werden soll.

Der Importer von Clerk.io kann so konfiguriert werden, dass er diese Parameter an Ihren Feed-Code sendet. Sie müssen lediglich die Anzahl der Objekte auswählen, die Sie pro Seite abrufen möchten.

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

{{limit}} enthält die Zahl, die Sie in den Importeinstellungen konfiguriert haben. {{offset}} beginnt bei 0 im ersten Aufruf und wächst kontinuierlich basierend auf limit.

Z.B.

• 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 Verwendung dieser Funktion bedeutet, dass Clerk.io aufhört, Objekte beim Importieren zu löschen, sodass Sie CRUD API-Aufrufe verwenden müssen, um Objekte aus der Datenbank von Clerk.io zu entfernen.

Die Multi-Feed-Lösung unterstützt die optionale Funktion, nur die Daten zu senden, die sich seit einer bestimmten Anzahl von Tagen geändert haben, anstatt jedes Mal alle Daten zu senden.

Um dies zu tun, stellen Sie zunächst sicher, dass Ihr Feed so konfiguriert ist, dass er nur Objekte zurückgibt, die in einer bestimmten Anzahl von Tagen geändert wurden, wenn die Anfrage den Abfrageparameter modified_after enthält.

Fügen Sie dann eine Anzahl von Tagen im Feld Incremental time {{modified_after}} in den Importeinstellungen von Clerk.io hinzu.

Dies führt dazu, dass der Importer von Clerk.io alle Daten in der Datenbank beibehält und nur Objekte aktualisiert, die in den Feeds enthalten sind.

Um die Anzahl der Tage zu verwenden, die Sie konfiguriert haben, fügen Sie den Abfrageparameter modified_after zu Ihrem Feed hinzu und fügen Sie das Tag ein, das die Anzahl der Tage einfügt, die Sie konfiguriert haben. Zum Beispiel:

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

Sicherheit #

Wir empfehlen, dass der JSON-Feed nur eine SSL-verschlüsselte Verbindung akzeptiert und wenn möglich HTTP-Authentifizierung verwendet.

Darüber hinaus können Sie in den Importeinstellungen Token-Authentifizierung aktivieren. Clerk.io wird dann bei jeder HTTP-Anfrage einen Autorisierungsheader einfügen, den Sie überprüfen müssen, bevor Sie die Daten zurückgeben:

X-Clerk-Authorization: Bearer THE_TOKEN

Sie können das Token mit einer POST-Anfrage 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-Zeitstempel, wann der Feed zuletzt aktualisiert wurde. Der Importer von Clerk.io verwendet dies, um zu identifizieren, ob neue Daten abgerufen werden sollen.
• strict: Wenn true, werden alle Daten unverändert importiert. Wenn false, versucht Clerk.io, die Daten aufzuräumen, zum Beispiel durch Entfernen von doppelten Produkten oder Kategorien und Umwandeln von als Strings gespeicherten Zahlen in Ganzzahlen oder Fließkommazahlen.

Beispiel Feed #

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

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

Sicherheit #

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

Wir empfehlen, dass der JSON-Feed nur eine SSL-verschlüsselte Verbindung akzeptiert und wenn möglich HTTP-Authentifizierung verwendet.

Darüber hinaus bietet Clerk eine zusätzliche Sicherheitsebene, indem Sie überprüfen können, dass die Feed-Anfrage von einer vertrauenswürdigen Quelle (d.h. uns) stammt.

Das System basiert auf einem gemeinsamen Geheimnis; einem privaten API-Schlüssel, der in my.clerk.io unter Einstellungen > API-Schlüssel erstellt werden kann.

Alle Clerk.io-Anfragen über HTTP oder HTTPS enthalten zwei Abfrageparameter hash und salt.

salt ist einfach ein zufälliger String, der verwendet wird, um die Hash-Funktion zu salzen, während hash ein SHA512-Hash ist, der aus dem privaten API-Schlüssel auf folgende Weise berechnet wird:

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

Ein Beispielaufruf könnte die folgende URL sein:

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

Durch das Abrufen sowohl der salt- als auch der hash-Parameter aus der Anfrage können Sie die gleiche Berechnung auf Ihrem Server durchführen und die hash-Werte vergleichen, um zu bestätigen, dass sie gleich sind, was bedeutet, dass die Anfrage von Clerk.io stammt.