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 dieselbe 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 aufbewahrt.

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 Importeur 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.

Nullwerte #

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 selben 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, jedoch 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 stellt ein einzelnes Produkt dar. 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": ["Charcoal","Ruby","Emerald"],
    "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": "Death Star - 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 behalten #

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 nutzen kann.

Um dies zu tun, fügen Sie das spezielle Attribut index: false zu den Produktobjekten hinzu, die ohne Indizierung behalten werden sollen. Clerk wird dann die Historie ihrer Verkäufe zur Anzeige von Ergebnissen verwenden, 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 stellt eine einzelne Kategorie dar. Clerk.io erstellt einen internen Kategorienbaum basierend auf den für jede Kategorie bereitgestellten Unterkategorien.

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 in der Regel nur während des ersten Imports gesendet werden und können dann wieder entfernt werden, um Serverkapazitäten 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 stellt eine einzelne Bestellung dar. 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 stellt einen einzelnen Kunden dar. 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 stellt eine einzelne Seite dar. 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, Landing Pages, Marken-Seiten 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 trennen.

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. Derzeit unterstützen wir 54 Sprachen. Wenn Ihre Sprache nicht auf der Liste steht, wählen Sie eine verwandte Sprache oder einfach “english”. Es wird trotzdem funktionieren, aber die Grammatikneutralisierung in der Suche wird weniger effektiv sein.

• afrikaans
• albanisch
• arabisch
• armenisch
• aserbaidschanisch
• baskisch
• belarussisch
• bengalisch
• bosnisch
• bulgarisch
• katalanisch
• chinesisch
• kroatisch
• tschechisch
• dänisch
• niederländisch
• englisch
• estnisch
• finnisch
• französisch
• galizisch
• georgisch
• deutsch
• griechisch
• hebräisch
• hindi
• ungarisch
• isländisch
• indonesisch
• irisch
• italienisch
• japanisch
• koreanisch
• lettisch
• litauisch
• mazedonisch
• malaiisch
• norwegisch
• persisch
• polnisch
• portugiesisch
• rumänisch
• russisch
• serbisch
• slowakisch
• slowenisch
• spanisch
• schwedisch
• filipino
• thailändisch
• türkisch
• ukrainisch
• urdu
• vietnamesisch

Mehrere Feeds #

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

Bei 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 Importeur von Clerk.io kann so konfiguriert werden, dass er diese Parameter an Ihren Feed-Code sendet. Sie müssen einfach 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ören wird, 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 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 in das Feld mit der Bezeichnung Incremental time {{modified_after}} ein, das in den Importeinstellungen von Clerk.io zu finden ist.

Dies führt dazu, dass der Importeur von Clerk.io alle Daten in der Datenbank behä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 hinzu, 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 einen Autorisierungsheader bei jeder HTTP-Anfrage 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 Importeur von Clerk.io verwendet dies, um zu identifizieren, ob neue Daten abgerufen werden sollten.
• strict: Wenn true, werden alle Daten unverändert importiert. Wenn false, wird Clerk.io versuchen, die Daten zu bereinigen, z.B. durch Entfernen von doppelten Produkten oder Kategorien und Umwandeln von als Strings dargestellten 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 Entwickler > 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

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