Data Feeds

Überblick #

Unabhängig von Ihrer E-Commerce-Plattform und davon, ob eine Integration besteht 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

Beide Lösungen verwenden die gleiche Objektstruktur, bieten jedoch unterschiedliche Möglichkeiten zur Absicherung und zum Importieren, die in diesem Leitfaden beschrieben werden.

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

Wir empfehlen, den/die JSON-Feed(s) mindestens einmal pro Tag zu generieren, idealerweise jedoch häufiger. Sie können auch nach Bedarf generiert werden, wenn Clerk.io’s Importer sie anfordert.

Der/die Feed(s) sollten über eine URL erreichbar sein, die von den Servern von Clerk.io zugänglich 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 sind eine sichere Fehlerquelle im Laufe der Zeit. Falls ein Attribut für ein bestimmtes Produkt, eine Kategorie oder Bestellung nicht existiert, lassen Sie das Attribut einfach weg.

ID-Wert-Typen #

Wir empfehlen dringend, Ganzzahlen als IDs zu verwenden, aber auch Strings sind möglich. Sie müssen in Ihrem Feed immer bei einem Typ bleiben, also entweder nur ganze Zahlen oder nur Strings für alle Objekt-IDs verwenden.

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.

Verwenden Sie keine Bindestriche oder Sonderzeichen in den Attributnamen, da diese beim Sync ignoriert werden.

Objektstruktur #

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

Objekte müssen mindestens die erforderlichen Felder für den jeweiligen Typ enthalten, damit die KI von Clerk.io ordnungsgemäß funktioniert. Optional können sie weitere Felder enthalten, die in der E-Commerce-Plattform vorhanden sind.

Produkte #

Jedes Objekt repräsentiert ein einzelnes Produkt. Wenn Sie konfigurierbare Produkte haben, empfehlen wir, nur das Elternprodukt zu senden und Attribute wie color, size, material usw. zu nutzen, die die Kindprodukte beschreiben.

Im Folgenden sehen Sie die erforderlichen sowie empfohlene Felder, 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 ohne Indexierung behalten #

In einigen Setups möchten Sie Produkte in der Clerk.io-Datenbank behalten, ohne dass sie irgendwo angezeigt werden.

Wenn Sie z.B. Tickets oder gebrauchte Artikel verkaufen, die nur für eine begrenzte Zeit verfügbar sind und dann nie wieder, empfiehlt es sich, den Verlauf dieser Produkte zu bewahren, damit Clerk ihn zur Verbesserung der Ergebnisse nutzen kann.

Dazu fügen Sie das spezielle Attribut index: false bei den Produktobjekten hinzu, die gespeichert, aber nicht indexiert werden sollen. Clerk verwendet dann die Verkaufshistorie dieser Produkte, aber sie werden in keiner API-Abfrage angezeigt.

Für alle anderen 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 einen internen Kategoriebaum auf Basis der angegebenen Unterkategorien für jede Kategorie.

Im Folgenden sehen Sie die erforderlichen Felder und Beispiele von optionalen Feldern, die häufig 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 im Allgemeinen nur beim ersten Import gesendet werden und können dann entfernt werden, um Serverkapazität zu sparen. Sie können über unsere CRUD API gelöscht werden.

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

Im Folgenden sehen Sie die erforderlichen und optionalen Felder. Um Paketdaten aufzunehmen, fügen Sie ein tracking-Array zur Bestellung hinzu. Senden Sie Pakete nicht als separates Top-Level-Objekt.

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,
    "tracking": [
      {
        "tracking_code": "ABC123",
        "tracking_link": "https://carrier.example/ABC123",
        "status": "SENT",
        "status_text": "Out for delivery"
      }
    ]
 },
  {
    "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 steht für einen einzelnen Kunden. Die angegebenen Attribute werden mit der email oder customer-ID der Bestellungen verknüpft, um ein einheitliches Kundenprofil für die Audience-Segmentierung zu erstellen.

Im Folgenden sehen Sie die erforderlichen sowie optionale Felder, 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 steht für eine einzelne Seite. Seiten sind generell alle Arten von E-Commerce-Inhalten, die nicht als Produkt oder Kategorie klassifiziert sind – zum Beispiel Artikel, Blogbeiträge, Landingpages, Markenseiten und andere Textinhalte.

Im Folgenden sehen Sie die erforderlichen sowie optionale Felder, die häufig genutzt 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 mit der Sprache der Inhalte konfiguriert werden, wodurch Search Grammatik und Rechtschreibfehler besser versteht.

Darüber hinaus haben Kunden aus verschiedenen Regionen oder Ländern unterschiedliche Vorlieben und Suchmuster, sodass es auch sinnvoll ist, das Bestelldaten in verschiedene Stores aufzuteilen.

Alternativ können Sie mehrsprachige JSON-Feeds erstellen, bei denen alle Textattribute als Objekte mit Sprachcodes als Keys und Übersetzungen als Werte angegeben werden.

Alle Textattribute müssen Sprachschlüssel enthalten, auch wenn der Inhalt derselbe ist, um die Suchfunktion für die Sprache zu gewährleisten.

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

Beispiel-Mehrsprachigkeits-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. Wir unterstützen aktuell 54 Sprachen. Falls Ihre Sprache nicht in der Liste steht, wählen Sie eine verwandte Sprache oder einfach “english”. Es funktioniert trotzdem, allerdings ist die Grammatik-Normalisierung in Search 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 er effizient für Ihren Server ist und höchste Kontrolle bietet.

Bei dieser Methode erstellen Sie einzelne Feed-Dateien für jedes Ihrer Objekte. Dazu wird die Synchronisationsmethode Clerk.io JSON Feed V2. verwendet.

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 eine optionale Funktion, die es Ihnen ermöglicht, Ergebnisse zu paginieren, indem Sie Ihren Feed so programmieren, dass er folgende Query-Parameter akzeptiert:

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

Clerk.io’s Importer kann so konfiguriert werden, dass er diese Parameter an Ihren Feed übergibt. Sie müssen nur die Menge der Objekte pro Seite auswählen.

Bei der Konfiguration Ihres Feed-URLs können Sie dann {{limit}} und {{offset}} an die URL anhängen.

{{limit}} enthält die von Ihnen im Importer festgelegte Anzahl. {{offset}} startet beim ersten Aufruf bei 0 und wächst dann entsprechend limit.

Beispiel:

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

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

URL #

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

Inkremente #

Wenn Sie diese Funktion nutzen, löscht Clerk.io beim Import keine Objekte mehr automatisch. Sie müssen nun CRUD API calls verwenden, um Objekte aus der Datenbank zu löschen.

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

Dazu stellen Sie sicher, dass Ihr Feed bei Angabe des Parameters modified_after nur Objekte zurückgibt, die sich in den angegebenen Tagen geändert haben.

Dann tragen Sie im Feld Incremental time {{modified_after}} in Clerk.io’s Importer-Einstellungen eine Anzahl an Tagen ein.

Dadurch speichert Clerk.io’s Importer alle Daten dauerhaft in der Datenbank und aktualisiert jeweils nur Objekte, die im Feed enthalten sind.

Um die festgelegte Anzahl Tage zu nutzen, fügen Sie den Query-Parameter modified_after in Ihren Feed ein und verwenden die Tag-Ersetzung zur Übergabe der eingestellten Anzahl Tage, z.B.:

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

Sicherheit #

Wir empfehlen, dass Ihr JSON-Feed ausschließlich SSL-verschlüsselte Verbindungen akzeptiert und nach Möglichkeit HTTP-Authentifizierung nutzt.

Zusätzlich können Sie in den Importer-Einstellungen Token Authentication aktivieren. Clerk.io fügt dann einen Authorization Header zu jeder HTTP-Anfrage hinzu, den Sie vor Antwort auf die Anfrage prüfen müssen:

X-Clerk-Authorization: Bearer THE_TOKEN

Sie können das Token mit einer POST-Anfrage 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 #

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

• created: Ein Unix-Timestamp, wann der Feed zuletzt aktualisiert wurde. Clerk.io’s Importer nutzt dies, um zu erkennen, ob neue Daten abgerufen werden sollen.
• strict: Ist dieser Wert true, werden alle Daten exakt wie geliefert importiert. Bei false versucht Clerk.io, die Daten zu bereinigen, z.B. doppelte Produkte/Kategorien zu entfernen oder Zahlen die als String übermittelt wurden, in Integer/Floats zu konvertieren.

Beispiel-Feed #

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

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

Sicherheit #

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

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

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

Das System basiert auf einem geteilten Geheimnis: Ein Private API Key, der in my.clerk.io unter Developers > API Keys erstellt werden kann.

Alle Clerk.io-Requests via HTTP oder HTTPS enthalten die beiden Query-Parameter hash und salt.

salt ist nur ein zufälliger String zum Salzen der Hashfunktion, während hash ein SHA512-Hash aus dem Private API Key wie folgt ist:

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

Eine Beispielanfrage könnte folgendermaßen aussehen:

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

Indem Sie sowohl salt als auch hash aus der Anfrage entnehmen, können Sie die gleiche Berechnung auf Ihrem Server durchführen und die Hashwerte vergleichen, um zu bestätigen, dass sie gleich sind. So wissen Sie, dass die Anfrage von Clerk.io kommt.