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 die gleiche Objektstruktur, bieten jedoch verschiedene Möglichkeiten zur Absicherung und zum Importieren, die in diesem Leitfaden aufgeführt sind.

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 Importieren aus der Datenbank. Bestellungen werden protokolliert und in der Datenbank behalten.

Wir empfehlen, die JSON-Feeds mindestens einmal täglich, idealerweise aber häufiger zu generieren. Sie können auch bei Bedarf generiert werden, wenn der Importer von Clerk.io sie anfordert.

Die Feeds sollten unter einer URL verfügbar sein, auf die Clerk.io-Server zugreifen können.

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 sind eine sichere Fehlerquelle auf lange Sicht. 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 nutzen. Sie müssen sich für einen Typ im Feed entscheiden, 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 aus verschiedenen Feldern bestehen, welche ihre Daten enthalten.

Objekte müssen mindestens die erforderlichen Felder für den Typ enthalten, damit die KI von Clerk.io ordnungsgemäß funktioniert. Optional können sie beliebig viele zusätzliche Attribute aus der E-Commerce-Plattform beinhalten.

Produkte #

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

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

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

Wenn Sie Tickets oder gebrauchte Artikel verkaufen, die eine Zeit lang verfügbar sind, bevor sie nie wiederkommen, ist es sinnvoll, die Historie dieser Produkte beizubehalten, sodass Clerk diese zur Verbesserung der Ergebnisse verwenden kann.

Fügen Sie dazu das spezielle Attribut index: false zu Produktobjekten hinzu, die nicht indiziert, aber behalten werden sollen. Clerk nutzt dann die Verkaufshistorie dieser Produkte zum Anzeigen von Ergebnissen, diese werden aber niemals in API-Abfragen 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 eine interne Kategoriebäume basierend auf den Unterkategorien, die für jede Kategorie angegeben werden.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, die häufig von E-Commerce-Shops 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 in der Regel nur beim Erstimport gesendet werden und können anschließend wieder entfernt werden, um Serverkapazität zu sparen. Sie können über unsere CRUD API gelöscht werden.

parcels-Daten können momentan nur via CRUD API synchronisiert werden. Die Dokumentation finden Sie hier.

Jedes Objekt repräsentiert eine einzelne Bestellung. Clerk.io nutzt die Produkt-IDs und E-Mail-Adressen/Kunden-IDs in Bestellungen, um das Kundenverhalten zu analysieren und Trends zu identifizieren. Zusammen mit products ist dies der wichtigste Objekttyp.

Unten sehen Sie die erforderlichen Felder sowie optionale Felder. Es ist nicht möglich, weitere 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 Kunden-ID aus Bestellungen zu einem einzigen Kundenprofil zwecks Audience-Segmentierung zusammengeführt.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, die häufig von E-Commerce-Shops 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 repräsentiert eine einzelne Seite. Seiten sind in der Regel alle Arten von E-Commerce-Inhalten, die nicht als Produkt oder Kategorie eingeordnet werden. Zum Beispiel Artikel, Blog-Beiträge, Landingpages, Marken-Seiten und andere Arten von Textinhalten.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, die häufig von E-Commerce-Shops 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 separaten Store anlegen. Jeder Store kann mit der Sprache des Inhalts konfiguriert werden, was dazu führt, dass Search Grammatik und Rechtschreibfehler deutlich besser versteht.

Darüber hinaus haben Kunden aus verschiedenen Regionen oder Ländern oft unterschiedliche Vorlieben und Suchmuster, weshalb es am besten ist, auch die Bestelldaten in verschiedene Stores zu trennen.

Alternativ können Sie mehrsprachige JSON-Feeds aufbauen, bei denen alle Textattribute als Objekte mit Sprachcodes als Schlüssel und deren Übersetzungen als Werte bereitgestellt werden.

Alle Textattribute müssen Sprach-Codes als Schlüssel haben, auch wenn der Inhalt gleich ist, um die Durchsuchbarkeit für die jeweilige Sprache sicherzustellen.

Wenn Sie API-Calls durchführen, geben Sie den Parameter language und den passenden Sprach-Code an, um die korrekten Daten abzurufen.

Mehrsprachiges Beispiel-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 dem exakten Namen angegeben werden. Wir unterstützen derzeit 54 Sprachen. Falls Ihre Sprache nicht unten aufgeführt ist, wählen Sie eine verwandte oder einfach “english”. Es funktioniert 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 effizient für Ihren Server ist und den höchsten Grad an Kontrolle bietet.

Mit diesem Ansatz bauen Sie individuelle Feed-Dateien für jedes Ihrer Objekte. Das verwendet die Sync-Methode 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

Output #

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

Paginierung #

Dies ist eine optionale Funktion, mit der Sie Ergebnisse paginieren können, indem Sie den Feed so programmieren, dass er folgende Query-Parameter akzeptiert:

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

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

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

{{limit}} enthält die Zahl, die Sie in den Importeinstellungen konfigurieren. {{offset}} beginnt beim ersten Aufruf mit 0 und wächst dann kontinuierlich auf Basis von limit.

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 #

Wenn Sie dieses Feature nutzen, löscht Clerk.io beim Importieren keine Objekte mehr. Sie müssen daher CRUD API-Aufrufe nutzen, um Objekte aus der Clerk.io-Datenbank zu entfernen.

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

Stellen Sie dazu zunächst sicher, dass Ihr Feed so programmiert ist, dass er nur Objekte zurückgibt, die sich innerhalb der angegebenen Tage geändert haben, wenn der Query-Parameter modified_after gegeben ist.

Geben Sie dann eine Anzahl von Tagen im Feld Incremental time {{modified_after}} in den Clerk.io-Importeinstellungen an.

Dadurch bleibt im Clerk.io-Importer die gesamte Datenbank erhalten und es werden nur die Objekte aktualisiert, die in den Feeds enthalten sind.

Um die konfigurierte Anzahl Tage zu verwenden, fügen Sie den Query-Parameter modified_after zu Ihrem Feed hinzu und verwenden Sie das Tag für die Anzahl der von Ihnen konfigurierten Tage. Zum Beispiel:

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

Sicherheit #

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

Außerdem kann in den Import-Einstellungen Token Authentication aktiviert werden. Clerk.io wird dann in jedem HTTP-Request einen Authorisation-Header mitsenden, den Sie überprüfen sollten, bevor Sie Daten zurückgeben:

X-Clerk-Authorization: Bearer THE_TOKEN

Sie können das Token mit einem POST-Request an den token/verify Endpunkt 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 #

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

• created: Ein UNIX-Timestamp, wann der Feed zuletzt aktualisiert wurde. Der Clerk.io-Importer verwendet dies, um festzustellen, ob neue Daten abgerufen werden sollen.
• strict: Bei true werden alle Daten exakt so importiert wie geliefert. Bei false versucht Clerk.io z.B. Duplikate von Produkten/Kategorien zu entfernen und Zahl-Strings in Integer/Floats umzuwandeln.

Beispiel-Feed #

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

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

Sicherheit #

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

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

Darüber hinaus bietet Clerk eine zusätzliche Sicherheitsschicht, indem sichergestellt werden kann, dass der Feed-Request aus einer vertrauenswürdigen Quelle (also von uns) kommt.

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

Alle HTTP- oder HTTPS-Requests von Clerk.io enthalten zwei Query-Parameter: hash und salt.

salt ist lediglich ein zufälliger String, der den Hash-Funktion “salzt”, während hash ein SHA512-Hash ist, der vom Private API Key auf folgende Weise berechnet wird:

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

Ein Beispiel-Aufruf könnte folgende URL sein:

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

Indem Sie sowohl salt als auch hash von der Anfrage extrahieren, können Sie dieselbe Berechnung auf Ihrem Server durchführen und die Werte vergleichen, um zu bestätigen, dass die Anfrage tatsächlich von Clerk.io stammt.