Data Feeds

Überblick #

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

Wir unterstützen zwei verschiedene Varianten der Feeds:

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

Beide Lösungen verwenden die gleiche Objektstruktur, aber sie bieten verschiedene Möglichkeiten, sie zu sichern und zu importieren, die in diesem Leitfaden erläutert werden.

Alle Objekttypen außer Bestellungen werden aus den Feeds mit der Datenbank von Clerk.io gespiegelt. Wenn Sie ein Objekt aus dem Feed entfernen, entfernt Clerk.io es beim Importieren auch aus der Datenbank. Bestellungen werden protokolliert und in der Datenbank gespeichert.

Wir empfehlen, den JSON-Feed(s) mindestens einmal täglich – idealerweise häufiger – zu generieren. Sie können auch bei Bedarf generiert werden, wenn der Clerk.io Importer 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 (Objekt).

Null-Werte #

Nicht behandelte null-Werte sind ein sicherer Weg, wie sich im Laufe der Zeit Fehler einschleichen. Wenn ein Attribut für ein bestimmtes Produkt, eine Kategorie oder eine Bestellung nicht existiert, lassen Sie das Attribut einfach weg.

ID-Wertetypen #

Wir empfehlen dringend, Ganzzahlen als IDs zu verwenden, aber es ist auch möglich, Strings zu nutzen. Sie müssen sich in Ihrem Feed immer auf einen Typ festlegen, d.h. alle IDs für Ihre Objekte müssen vom gleichen 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 in Attributnamen führt dazu, dass sie beim Sync ignoriert werden.

Objektstruktur #

JSON-Feeds bestehen aus einer Liste von Objekten, die eine Reihe von Feldern als ihre Daten enthalten.

Objekte müssen mindestens die erforderlichen Felder für den jeweiligen Typ enthalten, damit die KI von Clerk.io korrekt funktioniert. Optional können sie beliebige zusätzliche Attribute Ihrer E-Commerce-Plattform enthalten.

Produkte #

Jedes Objekt stellt ein einzelnes Produkt dar. Wenn Sie konfigurierbare Produkte anbieten, empfehlen wir, nur das übergeordnete Produkt zu senden und Attribute wie color, size, material usw. zu den Kindern hinzuzufügen.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale Felder, die häufig von E-Commerce-Shops genutzt 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 ohne Indexierung behalten #

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

Wenn Sie z.B. Tickets oder gebrauchte Artikel verkaufen, die zeitlich begrenzt verfügbar sind, ist es sinnvoll, die Historie dieser Produkte zu bewahren, damit Clerk daraus bessere Ergebnisse ziehen kann.

Fügen Sie dazu das spezielle Attribut index: false zu Produktobjekten hinzu, die zwar gespeichert, aber nicht indexiert werden sollen. Clerk verwendet dann deren Verkaufshistorie für die Ergebnisanzeige, aber sie erscheinen nie in API-Ausgaben.

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

Kategorien #

Jedes Objekt steht für eine einzelne Kategorie. Clerk.io baut basierend auf den bereitgestellten Unterkategorien für jede Kategorie einen internen Kategoriebaum auf.

Unten finden Sie die erforderlichen Felder und Beispiele für optionale Felder, die häufig von Shops genutzt 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 in der Regel nur beim ersten Import gesendet werden und können danach 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. Siehe die Dokumentation hier.

Jedes Objekt steht für eine einzelne Bestellung. Clerk.io nutzt die Produkt-IDs und E-Mail-Adresse/Kundennummer innerhalb der Bestellungen zur Analyse des Kundenverhaltens und zur Erkennung von Trends. Zusammen mit products ist dies der wichtigste Objekttyp.

Unten finden 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 customer-ID aus Bestellungen zusammengeführt, um ein Kundenprofil zur Nutzung für die Audience-Segmentierung zu erstellen.

Unten finden Sie die erforderlichen Felder und Beispiele für optionale Attribute, die häufig genutzt 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 stellt eine einzelne Seite dar. Seiten sind im Allgemeinen alle Arten von E-Commerce-Inhalten, die nicht als Produkt oder Kategorie klassifiziert sind. Das können z.B. Artikel, Blogposts, Landeseiten, Marken-Seiten und andere textbasierte Inhalte sein.

Unten sehen Sie die erforderlichen Felder und Beispiele von optionalen, häufig verwendeten Feldern.

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 Shop erstellen. Jeder Shop kann mit der Sprache des Inhalts konfiguriert werden, wodurch Search Grammatik und Rechtschreibfehler deutlich besser versteht.

Außerdem haben Kunden aus verschiedenen Regionen und Ländern oft unterschiedliche Präferenzen und Suchmuster. Deshalb funktioniert es am besten, auch die Bestelldaten in verschiedene Shops aufzuteilen.

Eine Alternative dazu ist der Aufbau von mehrsprachigen JSON-Feeds, bei denen alle Textattribute als Objekte mit Sprachcodes als Schlüssel und deren Übersetzungen als Werte angegeben werden.

Alle Textattribute müssen Sprachschlüssel haben, selbst wenn der Inhalt derselbe ist, um ihre Durchsuchbarkeit zu gewährleisten.

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

Beispiel: mehrsprachiges 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
 }
]

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 exakten Namen angegeben werden. Aktuell unterstützen wir 54 Sprachen. Wenn Ihre Sprache nicht in der Liste ist, wählen Sie eine verwandte Sprache oder einfach “english”. Es funktioniert dann trotzdem, aber die Grammatikneutralisierung in Search ist 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 er serverseitig effizient und besonders kontrollierbar ist.

Dabei erstellen Sie einzelne Feed-Dateien für jeden Objekttyp. Dies verwendet die Sync-Methode namens Clerk.io JSON Feed V2.

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

Jeder Feed soll ein Array von Objekten enthalten.

URL #

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

Ausgabe #

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

Pagination #

Dies ist ein optionales Feature, das Ihnen erlaubt, Ergebnisse seitenweise bereitzustellen, indem Ihr Feed die folgenden Abfrageparameter verarbeitet:

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

Clerk.io’s Importer kann so konfiguriert werden, dass er diese Parameter an den Feed übergibt. Sie müssen dann nur angeben, wie viele Objekte pro Page abgerufen werden sollen.

Wenn Sie Ihre Feed-URL konfigurieren, können Sie {{limit}} und {{offset}} als Query-Parameter anfügen.

{{limit}} enthält die Anzahl, die Sie in den Importer-Einstellungen konfigurieren. {{offset}} startet bei 0 im ersten Aufruf und wächst bei weiteren Aufrufen um jeweils limit.

Beispiel:

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

Die Abbruchbedingung: Ihr Feed gibt ein leeres Array zurück.

URL #

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

Inkremente #

Wenn Sie diese Funktion aktivieren, löscht Clerk.io beim Import keine Objekte mehr. Sie müssen dann die CRUD API nutzen, um Objekte aus der Clerk.io-Datenbank zu entfernen.

Die Mehr-Feed-Lösung unterstützt das optionale Feature, statt immer alle Daten nur die seit einer bestimmten Anzahl von Tagen geänderten Daten zu senden.

Stellen Sie dazu sicher, dass Ihr Feed so programmiert ist, dass er bei Übergabe des Abfrageparameters modified_after nur Objekte zurückgibt, die innerhalb der angegebenen Tage geändert wurden.

Anschließend geben Sie in den Clerk.io-Importer-Einstellungen einen Wert für Incremental time {{modified_after}} an.

Dadurch aktualisiert der Importer nur die Objekte, die in den Feeds enthalten sind und belässt alle übrigen in der Datenbank.

Verwenden Sie dazu den Parameter modified_after zusammen mit dem Tag, das die von Ihnen konfigurierte Anzahl an Tagen einfügt. Z.B.:

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

Sicherheit #

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

Zusätzlich können Sie in den Importer-Einstellungen Token Authentication aktivieren. Clerk.io sendet dann bei jedem HTTP-Aufruf einen Authorization Header, den Sie vor der Datenlieferung prüfen sollten:

X-Clerk-Authorization: Bearer THE_TOKEN

Sie können das Token mit einem POST-Request zum token/verify Endpoint prü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 #

Zusätzlich zu den Objekten selbst werden zwei weitere Parameter unterstützt:

• created: Ein Unix-Zeitstempel, wann der Feed zuletzt aktualisiert wurde. Clerk.io nutzt diesen Wert, um zu erkennen, ob neue Daten abgerufen werden müssen.
• strict: Wenn true, werden alle Daten wie geliefert importiert. Bei false versucht Clerk.io, Daten zu bereinigen, z.B. doppelte Produkte/Kategorien zu entfernen oder String-Zahlen in Integer/Floats zu konvertieren.

Beispiel-Feed #

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

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

Sicherheit #

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

Wir empfehlen, dass der JSON-Feed ausschließlich über eine SSL-verschlüsselte Verbindung abgerufen und nach Möglichkeit HTTP-Authentifizierung verwendet wird.

Zusätzlich bietet Clerk eine weitere Sicherheitsebene, um sicherzustellen, dass Feed-Anfragen von einer vertrauenswürdigen Quelle (also von uns) kommen.

Dieses System basiert auf einem Shared Secret; einem Private API Key, der in my.clerk.io unter Developers > API Keys erstellt werden kann.

Alle Clerk.io-Anfragen per HTTP/HTTPS enthalten zwei Query-Parameter: hash und salt.

salt ist eine Zufallszeichenkette für die Salzung der Hashfunktion. hash ist ein SHA512-Hash, gebildet aus dem Private API Key wie folgt:

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

Eine Beispielanfrage-URL könnte so aussehen:

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

Indem Sie salt und hash aus dem Request abrufen, können Sie die gleiche Berechnung auf Ihrem Server durchführen und die Hashwerte vergleichen, um zu bestätigen, dass die Anfrage von Clerk.io stammt.