Data Feeds

Überblick #

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

Wir unterstützen zwei unterschiedliche 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 verschiedene Funktionen zur Sicherung und zum Import, die in diesem Leitfaden erläutert werden.

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

Wir empfehlen, die JSON-Feeds mindestens einmal täglich zu generieren, idealerweise häufiger. 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, die von Clerk.io’s Servern erreichbar ist.

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

Datentypen #

Wir unterstützen Attribute der Typen: int, float, str, array, bool, dict (object).

Null-Werte #

Ungeprüfte null-Werte führen leicht zu Fehlern im Laufe der Zeit. Wenn 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, Integer als IDs zu verwenden, aber Strings sind ebenfalls möglich. Im Feed muss jedoch immer nur ein Typ verwendet werden, d.h. alle IDs eines Objekttyps müssen denselben Typ haben.

Attributnamen #

Objektattribute dürfen nur alphanumerische Werte (A-Z, 0-9) und Unterstriche enthalten.
Ein gültiger Attributname könnte also z.B. brand_name, aber nicht läbel-mærke sein.

Die Verwendung von Bindestrichen oder Sonderzeichen in den Attributnamen führt dazu, dass sie beim Sync ignoriert werden.

Objekt-Struktur #

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

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

Produkte #

Jedes Objekt stellt ein einzelnes Produkt dar. Bei konfigurierbaren Produkten empfehlen wir, nur das Elternprodukt zu senden und Attribute wie color, size, material etc. für die Kindprodukte anzugeben.

Unten sehen Sie die erforderlichen Felder sowie empfohlene, 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 sie zu indexieren #

Für manche Setups möchten Sie Produkte in Clerk.io’s Datenbank behalten, ohne sie in den Suchergebnissen anzuzeigen.

Wenn Sie z. B. Tickets oder Gebrauchtwaren verkaufen, die eine gewisse Zeit verfügbar sind und dann nie wieder, ist es sinnvoll, die Historie dieser Produkte zu erhalten, damit Clerk die Daten zur Ergebnisverbesserung nutzen kann.

Dazu fügen Sie das spezielle Attribut index: false jenen Produktobjekten hinzu, die zwar behalten, aber nicht indexiert werden sollen. Clerk verwendet dann deren Verkaufshistorie für das Ranking, zeigt sie aber nie in API-Ausgaben.

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 baut einen internen Kategoriebaum basierend auf den bereitgestellten Unterkategorien jeder Kategorie.

Unten sehen Sie die erforderlichen Felder und Beispiele für optionale, 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 nicht gelöscht, wenn sie aus dem Feed entfernt werden. Sie müssen sie in der Regel nur beim ersten Import schicken und können sie anschließend entfernen, um Serverressourcen zu sparen. Das Löschen ist über unsere CRUD API möglich.

Jedes Objekt entspricht einer einzelnen Bestellung. Clerk.io nutzt die Produkt-IDs und E-Mail/Kunden-ID zur Analyse des Kundenverhaltens und zur Erkennung von Trends. Zusammen mit products ist dies der wichtigste Objekttyp.

Unten finden Sie die erforderlichen Felder und die optionalen Felder. Um Paketdaten einzubeziehen, fügen Sie ein tracking-Array zur Bestellung hinzu. Pakete dürfen nicht als separates Top-Level-Objekt gesendet werden.

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 bereitgestellten Attribute werden mit der email-Adresse oder Kunden-ID aus Bestellungen zusammengeführt, um ein einheitliches Kundenprofil für die Segmentierung mit Audience zu erstellen.

Unten finden Sie die erforderlichen Felder sowie Beispiel für optionale, die oft 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 steht für eine einzelne Seite. Seiten sind alle Arten von E-Commerce-Inhalten, die nicht als Produkt oder Kategorie gelten, z.B. Artikel, Blog-Beiträge, Landingpages, Marken-Seiten oder ähnlicher Content.

Unten sind die erforderlichen Felder und Beispiele für optionale, wie sie oft 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 auf die Sprache des Inhaltes konfiguriert werden, was Search die Grammatik und Rechtschreibfehler besser verstehen lässt.

Darüber hinaus haben Kunden aus verschiedenen Regionen oder Ländern meist unterschiedliche Vorlieben und Suchmuster. Das bedeutet, auch Bestelldaten sollten für die Stores getrennt synchronisiert werden.

Alternativ können Sie mehrsprachige JSON-Feeds erstellen, in denen sämtliche Textattribute als Objekte mit Sprachcodes als Keys sowie den Übersetzungen als Werte bereitgestellt werden.

Alle Textattribute müssen über Sprach-Keys verfügen, selbst wenn der Inhalt jeweils identisch ist, damit die Suche für die gewählte Sprache funktioniert.

Bei API-Aufrufen geben Sie den Parameter language sowie den zugehörigen Sprach-Key an, um die passenden Daten zu erhalten.

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
 }
]

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 genau mit ihrem Namen angegeben werden. Aktuell werden 54 Sprachen unterstützt. Sollte Ihre Sprache nicht in der Liste unten sein, wählen Sie eine ähnliche Sprache oder einfach “english”. Der Datentransfer funktioniert trotzdem, allerdings ist das Grammatik-Verständnis 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 #

Dieser Ansatz wird empfohlen, da er sehr effizient für Ihren Server ist und maximale Kontrolle bietet.

Dabei bauen Sie für jede Ihrer Objektklassen eine eigene Feed-Datei. Diese verwenden die Sync-Methode namens Clerk.io JSON Feed V2.

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

Jeder Feed muss ein Array von Objekten beinhalten.

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, um Ergebnisse zu paginieren, indem Sie Ihren Feed so programmieren, dass er folgende Query-Parameter akzeptiert:

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

Der Clerk.io-Importer kann so eingestellt werden, dass er diese Parameter an Ihrem Feed aufruft. Sie wählen dabei die gewünschte Objekte-Anzahl pro Seite.

Bei der Konfiguration Ihrer Feed-URL können Sie dann {{limit}} und {{offset}} verwenden, um die Daten als Query-Parameter anzuhängen.

{{limit}} enthält die konfigurierte Zahl aus den Importer-Einstellungen. {{offset}} startet bei 0 beim ersten Aufruf und steigt um den Wert von limit.

z.B.

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

Die Abbruch-Bedingung ist erreicht, wenn der Feed ein leeres Array zurückgibt.

URL #

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

Inkremente #

Die Nutzung dieser Funktion bedeutet, dass Clerk.io beim Import keine Objekte mehr löscht. Sie müssen CRUD API-Aufrufe zur Entfernung von Objekten aus Clerk.io’s Datenbank nutzen.

Die Multi-Feed-Lösung unterstützt die optionale Funktion, nur jene Daten zu übertragen, die sich innerhalb eines gewählten Zeitraums verändert haben, anstatt jedes Mal alle Daten zu senden.

Dazu richten Sie Ihren Feed so ein, dass er bei Angabe des Parameters modified_after im Request lediglich die Objekte zurückgibt, die in den letzten Tagen geändert wurden.

Geben Sie dann die Anzahl der gewünschten Tage im Feld Incremental time {{modified_after}} in den Clerk.io-Importer-Einstellungen an.

Dadurch bleibt der Datenbestand in Clerk.io erhalten, und nur Daten zu aktualisierten Objekten werden aus dem Feed übernommen.

Um Ihre konfigurierte Anzahl von Tagen zu nutzen, hängen Sie den Query-Parameter modified_after an Ihren Feed an und setzen Sie das Tag ein, das die Anzahl von 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 eine SSL-verschlüsselte Verbindung akzeptiert und möglichst HTTP-Authentifizierung nutzt.

Zusätzlich können Sie in den Importer-Einstellungen Token Authentication aktivieren. Clerk.io sendet dann bei jedem HTTP-Request einen Authorisation-Header, den Sie vor Auslieferung der Daten verifizieren sollten:

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 #

Bei diesem Ansatz bündeln Sie alle Ihre Objekte in einer einzigen JSON-Datei. Diese nutzt die Sync-Methode namens Clerk.io JSON Feed.

Parameter #

Abgesehen von den Objekten selbst unterstützt der Ansatz zwei zusätzliche Parameter:

• created: Ein Unix-Timestamp, wann der Feed zuletzt aktualisiert wurde. Clerk.io’s Importer verwendet diesen, um zu erkennen, ob neue Daten abgerufen werden sollen.
• strict: Bei true werden alle Daten exakt übernommen. Bei false versucht Clerk.io, die Daten zu bereinigen, z.B. doppelte Produkte oder Kategorien zu entfernen und String-Zahlen in Integer oder Float umzuwandeln.

Beispiel-Feed #

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

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

Sicherheit #

Ihre Daten sind extrem geschäftskritisch, daher ist Datensicherheit oberste Priorität!

Wir empfehlen, dass der JSON-Feed nur SSL-verschlüsselt erreichbar ist und möglichst auch HTTP-Authentifizierung verwendet.

Clerk bietet darüber hinaus eine zusätzliche Sicherheitsebene, indem Sie sicherstellen können, dass Feed-Anfragen wirklich von uns stammen.

Das System basiert auf einem geteilten Secret; ein Private API Key, den Sie in my.clerk.io unter Developers > API Keys erstellen können.

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

salt ist eine Zufallszeichenfolge zur Salzung der Hash-Funktion, während hash ein SHA512-Hash ist, berechnet aus dem Private API Key wie folgt:

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

Ein Beispielaufruf könnte so aussehen:

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

Indem Sie die Parameter salt und hash aus dem Request holen, können Sie die Berechnung serverseitig ebenfalls durchführen und den Hash vergleichen, um sicherzustellen, dass die Anfrage von Clerk.io stammt.