Data Feeds

Übersicht #

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 verschiedene Varianten der Feeds:

• Mehrere Dateien für unterschiedliche Objekte
• Eine einzelne Datei, in der alle Objekte enthalten sind

Beide Lösungen nutzen die gleiche Objektstruktur, bieten aber verschiedene Funktionen zur Absicherung und zum Import, die in diesem Leitfaden beschrieben werden.

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

Wir empfehlen, die JSON-Feeds mindestens einmal am Tag, idealerweise jedoch häufiger, zu generieren. Sie können auch auf Abruf generiert werden, wenn der Importer von Clerk.io sie anfordert.

Die Feeds sollten unter einer URL verfügbar sein, die von Clerk.io-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 sind eine sichere Methode, um über die Zeit Fehler einzuschleichen. Wenn ein Attribut für ein bestimmtes Produkt, eine Kategorie oder Bestellung nicht existiert, lassen Sie das Attribut einfach weg.

ID-Werttypen #

Wir empfehlen dringend, Integer als IDs zu verwenden, aber Strings sind ebenfalls möglich. Sie müssen sich aber immer auf einen Typ in Ihrem Feed festlegen, das heißt, alle IDs für Ihre Objekte müssen vom gleichen Typ sein.

Attributnamen #

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

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

Objektstruktur #

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

Objekte müssen mindestens die für den Typ erforderlichen Felder enthalten, damit die KI von Clerk.io korrekt funktioniert, optional können sie alle weiteren Attribute enthalten, die in der E-Commerce-Plattform verfügbar sind.

Produkte #

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

Nachfolgend sehen Sie die erforderlichen Felder und empfohlene Felder, die von E-Commerce-Shops häufig 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 behalten ohne Indexierung #

Für manche Setups möchten Sie Produkte zwar in der Clerk.io-Datenbank behalten, aber diese in keinen Ergebnissen anzeigen.

Wenn Sie z. B. Tickets oder gebrauchte Artikel verkaufen, die nur vorübergehend verfügbar sind, ist es sinnvoll, die Historie dieser Produkte beizubehalten, damit Clerk die Ergebnisse optimieren kann.

Fügen Sie dazu das spezielle Attribut index: false zu den Produktobjekten hinzu, die gespeichert, aber nicht indiziert werden sollen. Clerk verwendet dann die Verkaufshistorie für Empfehlungen, diese Produkte werden aber nie in API-Aufrufen angezeigt.

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

Kategorien #

Jedes Objekt repräsentiert eine einzelne Kategorie. Clerk.io erstellt einen internen Kategoriebaum basierend auf den untergeordneten Kategorien, die für jede Kategorie angegeben werden.

Nachfolgend sehen Sie die erforderlichen Felder und Beispiele für optionale Felder, die häufig von E-Commerce-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 dann 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 Dokumentation hier.

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

Nachfolgend sehen Sie die erforderlichen und optionalen 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 angegebenen Attribute werden mit den email- oder customer-IDs der Bestellungen zusammengeführt, um ein einzelnes Kundenprofil für die Segmentierung mit Audience zu erstellen.

Nachfolgend sehen Sie die erforderlichen Felder und Beispiele für optionale Felder, die von vielen 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 i. d. R. alle E-Commerce-Inhalte, die nicht als Produkt oder Kategorie klassifiziert sind, z. B. Artikel, Blogbeiträge, Landingpages, Markenseiten und andere Textinhalte.

Nachfolgend sehen Sie die erforderlichen Felder und Beispiele für optionale Felder, die E-Commerce-Händler häufig nutzen.

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 erstellen. Jeder Store kann mit der Sprache der Inhalte konfiguriert werden, sodass Search Grammatik- und Rechtschreibfehler deutlich besser versteht.

Darüber hinaus haben Kunden aus verschiedenen Regionen oder Ländern unterschiedliche Präferenzen und Suchmuster, weshalb es am besten funktioniert, die Bestelldaten ebenfalls in separaten Stores zu speichern.

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

Alle Textattribute müssen Sprach-Keys haben, auch wenn der Inhalt identisch ist, um die Durchsuchbarkeit zu gewährleisten.

Bei API-Abfragen geben Sie den Parameter language sowie den passenden Language-Key an, um die gewünschten Inhalte 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. Wir unterstützen derzeit 54 Sprachen. Sollte Ihre Sprache nicht in der Liste sein, wählen Sie eine verwandte Sprache oder einfach “english”. Es funktioniert weiterhin, jedoch 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 Ihnen die größte Kontrolle bietet.

Bei diesem Ansatz erstellen Sie einzelne Feed-Dateien für jede Objektart. 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

Ausgabe #

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

Paginierung #

Dies ist eine optionale Funktion, mit der Sie mit Ihrer Feed-Logik paginieren können, indem folgende Query-Parameter akzeptiert werden:

• limit: Die Anzahl von Objekten pro Seite.
• offset: Der Index des ersten Objekts einer Seite.

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

Wenn Sie Ihre Feed-URL konfigurieren, können Sie dann {{limit}} und {{offset}} als Query-Parameter anhängen.

{{limit}} enthält den Wert, den Sie in den Importer-Einstellungen definieren. {{offset}} startet beim ersten Aufruf bei 0 und wird dann basierend auf dem Wert von limit erhöht.

Beispiel:

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

Die Abbruch-Bedingung ist gegeben, wenn Ihr Feed ein leeres Array zurückliefert.

URL #

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

Inkremente #

Bei Nutzung dieser Funktion löscht Clerk.io beim Import keine Objekte mehr automatisch, 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 die Daten zu senden, die sich innerhalb einer festgelegten Anzahl von Tagen geändert haben, statt jedes Mal alle Daten zu übermitteln.

Dazu stellen Sie sicher, dass Ihr Feed so konfiguriert ist, dass er nur Objekte liefert, die sich innerhalb eines angegebenen Zeitraums geändert haben, wenn die Anfrage mit dem Parameter modified_after erfolgt.

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

Dadurch speichert der Importer von Clerk.io alle Daten in der Datenbank und aktualisiert nur Objekte, die in den Feeds enthalten sind.

Um die hinterlegte Anzahl von Tagen zu nutzen, geben Sie den Parameter modified_after in Ihrer Feed-URL an und fügen Sie das Tag hinzu, das die von Ihnen definierte Tagesanzahl einfügt. Beispiel:

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

Sicherheit #

Wir empfehlen, dass der JSON-Feed ausschließlich SSL-verschlüsselte Verbindungen akzeptiert und falls möglich HTTP-Authentifizierung verwendet.

Zusätzlich können Sie in den Importer-Einstellungen Token Authentication aktivieren. Clerk.io sendet dann bei jedem HTTP-Request einen Authorisierungs-Header, den Sie vor Rückgabe der Daten prüfen müssen:

X-Clerk-Authorization: Bearer THE_TOKEN

Sie können das Token mit einem POST-Request an den token/verify-Endpoint verifizieren:

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 #

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

• created: Ein Unix-Timestamp, wann der Feed zuletzt aktualisiert wurde. Der Importer von Clerk.io nutzt diesen Wert, um zu identifizieren, ob neue Daten abgerufen werden sollen.
• strict: Wenn true, werden alle Daten wie sie sind importiert. Bei false versucht Clerk.io die Daten aufzubereiten, etwa indem doppelte Produkte/Kategorien entfernt oder String-Zahlen in Integer/Floats umgewandelt werden.

Beispiel-Feed #

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

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

Sicherheit #

Ihre Daten sind höchst sensibel, daher ist Sicherheit von größter Bedeutung!

Wir empfehlen, dass der JSON-Feed ausschließlich SSL-verschlüsselte Verbindungen akzeptiert und falls möglich HTTP-Authentifizierung nutzt.

Zusätzlich bietet Clerk eine weitere Sicherheitsebene, mit der Sie sicherstellen können, dass Feed-Anfragen tatsächlich von uns stammen.

Das System basiert auf einem geteilten Geheimnis: Einem Private API Key, den Sie unter Developers > API Keys in my.clerk.io erzeugen können.

Alle Clerk.io-Anfragen via HTTP(s) enthalten die zwei Query-Parameter hash und salt.

salt ist einfach ein Zufallsstring, der für die Hashfunktion verwendet wird, während hash ein SHA512-Hash aus Ihrem Private API Key ist, auf folgende Weise berechnet:

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 der Anfrage auslesen, können Sie die gleiche Berechnung auf Ihrem Server durchführen und die Werte vergleichen, um zu bestätigen, dass die Anfrage von Clerk.io stammt.