Data Feeds

Panoramica #

Indipendentemente dalla tua piattaforma eCommerce, e che abbiamo o meno un’integrazione, puoi sempre sincronizzare i dati con Clerk.io tramite uno o più feed in formato JSON.

Supportiamo due diverse varianti dei feed:

• Più file per oggetti diversi
• Un unico file che contiene tutti gli oggetti

Le due soluzioni utilizzano la stessa struttura degli oggetti, ma dispongono di differenti funzionalità per la sicurezza e l’importazione, che vengono descritte in questa guida.

Tutti i tipi di oggetto tranne gli ordini vengono rispecchiati dai feed nel database di Clerk.io. Se rimuovi un oggetto dal feed, Clerk.io lo rimuoverà dal database durante l’importazione. Gli ordini sono registrati e mantenuti nel database.

Consigliamo di generare i feed JSON almeno una volta al giorno, ma idealmente più spesso. Possono anche essere generati su richiesta quando l’importatore di Clerk.io li richiede.

I feed devono essere disponibili su un URL accessibile dai server di Clerk.io.

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

Tipi di dati #

Supportiamo attributi di tipo: int, float, str, array, bool, dict (oggetto).

Valori Null #

Valori null non controllati possono portare facilmente a errori nel tempo. Se un attributo non esiste per un determinato prodotto, categoria o ordine, semplicemente ometti l’attributo.

Tipi di valore ID #

Raccomandiamo vivamente di usare interi come ID, ma è anche possibile usare stringhe. Devi sempre mantenere un solo tipo nel tuo feed, ovvero tutti gli ID devono essere dello stesso tipo.

Nomi attributi #

Gli attributi degli oggetti possono contenere solo valori alfanumerici (A-Z, 0-9) e underscore.
Quindi, un nome attributo valido può essere brand_name ma non läbel-mærke

L’uso di trattini o caratteri speciali nei nomi degli attributi farà sì che vengano ignorati nella sincronizzazione.

Struttura degli oggetti #

I feed JSON consistono in una lista di oggetti, con vari campi che compongono i loro dati.

Gli oggetti devono contenere almeno i campi obbligatori per il tipo, affinché l’AI di Clerk.io funzioni correttamente, e opzionalmente possono includere altri attributi disponibili dalla piattaforma eCommerce.

Prodotti #

Ogni oggetto rappresenta un singolo prodotto. Se hai prodotti configurabili, consigliamo di inviare solo il prodotto genitore, e includere attributi che descrivono i figli, come color, size, material, ecc.

Qui sotto puoi vedere i campi obbligatori ed esempi di campi opzionali più usati dagli eCommerce.

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

Tenere prodotti senza indicizzazione #

Per alcune configurazioni, potresti voler conservare i prodotti nel database di Clerk.io senza mostrarli mai nei risultati.

Se vendi biglietti o articoli usati che saranno disponibili per un periodo limitato prima di non tornare mai più, è una buona idea mantenere la cronologia di questi prodotti intatta, così Clerk potrà usarla per migliorare i risultati.

Per fare questo, aggiungi l’attributo speciale index: false agli oggetti prodotto che desideri mantenere senza indicizzarli. Clerk userà la cronologia delle loro vendite per mostrare i risultati, ma non saranno mai visibili in nessuna chiamata API.

Per tutti gli altri prodotti, ometti l’attributo o impostalo su index: true.

Categorie #

Ogni oggetto rappresenta una singola categoria. Clerk.io costruisce un albero interno delle categorie basandosi sulle sottocategorie fornite per ciascuna categoria.

Qui sotto puoi vedere i campi obbligatori ed esempi di campi opzionali più usati dagli eCommerce.

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

Ordini #

Gli ordini sono registrati e non vengono eliminati se rimossi dal feed. Generalmente devono essere inviati solo durante la prima importazione e poi possono essere rimossi per risparmiare capacità del server. Possono essere eliminati tramite la CRUD API.

I dati parcels possono essere sincronizzati attualmente solo via CRUD API. Consulta la documentazione qui.

Ogni oggetto rappresenta un singolo ordine. Clerk.io usa gli ID dei prodotti e l’indirizzo email/ID cliente negli ordini per analizzare il comportamento dei clienti e individuare tendenze. Insieme ai products, è il tipo di oggetto più importante.

Qui sotto puoi vedere i campi obbligatori e opzionali. Non è possibile inviare attributi aggiuntivi per gli ordini.

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

Clienti #

Ogni oggetto rappresenta un singolo Cliente. Gli attributi forniti vengono poi uniti con l’email o l’ID customer dagli ordini per creare un profilo unico del cliente per la segmentazione Audience.

Qui sotto puoi vedere i campi obbligatori ed esempi di campi opzionali più usati dagli eCommerce.

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

Pagine #

Ogni oggetto rappresenta una singola pagina. Le pagine sono generalmente tutti i tipi di contenuti eCommerce che non sono classificati come prodotto o categoria. Possono essere articoli, blog post, landing page, pagine di brand e altri tipi di contenuti scritti.

Qui sotto puoi vedere i campi obbligatori ed esempi di campi opzionali più usati dagli eCommerce.

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

Multilingua #

Clerk.io funziona al meglio quando crei diversi Stores per ogni lingua. Ogni Store può essere configurato con la lingua dei contenuti, permettendo a Search di comprendere molto meglio la grammatica e gli errori di scrittura.

Inoltre, i clienti di diverse regioni o nazioni tendono ad avere preferenze e pattern di ricerca differenti, quindi è meglio separare anche i dati degli ordini in Store differenti.

In alternativa, puoi costruire feed JSON multilingua, dove tutti gli attributi di testo sono forniti come oggetti con i codici lingua come chiavi, e le rispettive traduzioni come valori.

Tutti gli attributi di testo devono avere chiavi lingua anche se il contenuto rimane lo stesso, per garantire la ricercabilità nella lingua corrispondente.

Quando effettui chiamate API, includi il parametro language e la chiave lingua corrispondente, per recuperare i dati corretti.

Esempio JSON multilingua #

[
  {
    "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
 }
]

Esempio di chiamata #

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'

Lingue supportate #

La lingua deve essere specificata con il nome esatto. Attualmente supportiamo 54 lingue. Se la tua lingua non è nella lista sotto, scegli una lingua correlata o semplicemente “english”. Funzionerà comunque, ma la neutralizzazione grammaticale in Search sarà meno efficace.

• 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

Feed multipli #

Questo è l’approccio raccomandato perché è efficiente per il tuo server e offre il massimo grado di controllo.

Con questo metodo, costruisci file feed separati per ciascun oggetto. Usa il metodo di sincronizzazione chiamato Clerk.io JSON Feed V2.

Sono supportati content-type: application/x-ndjson o application/json.

Ogni feed deve contenere un array di oggetti.

URL #

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

Output #

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

Paginazione #

Questa è una funzionalità opzionale che ti permette di paginare i risultati programmando il feed per accettare i seguenti parametri di query:

• limit: Numero di oggetti da restituire per pagina.
• offset: Indice del primo oggetto da restituire in una pagina.

L’importatore di Clerk.io può essere configurato per inviare questi parametri al tuo feed. Devi solo selezionare quanti oggetti vuoi ricevere per pagina.

Quando configuri l’URL del feed, puoi poi usare {{limit}} e {{offset}} per aggiungere i dati come parametri di query.

{{limit}} conterrà il numero che imposti nelle impostazioni dell’importatore. {{offset}} partirà da 0 nella prima chiamata e crescerà progressivamente in base a limit.

Esempio:

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

La condizione di arresto si verifica quando il feed restituisce un array vuoto.

URL #

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

Incrementi #

L’uso di questa funzionalità farà sì che Clerk.io smetta di eliminare oggetti durante l’importazione, quindi dovrai usare le chiamate CRUD API per rimuovere gli oggetti dal database di Clerk.io.

La soluzione multi-feed supporta la funzionalità opzionale di inviare solo i dati che sono cambiati da un certo numero di giorni, invece di inviare tutti i dati ogni volta.

Per farlo, assicurati che il tuo feed sia configurato per restituire solo oggetti che sono cambiati in una determinata quantità di giorni, quando la richiesta include il parametro di query modified_after.

Poi, inserisci un numero di giorni nel campo chiamato Incremental time {{modified_after}} nelle impostazioni dell’importatore di Clerk.io.

Questo farà sì che l’importatore mantenga tutti i dati nel database e aggiorni solo gli oggetti inclusi nei feed.

Per usare il numero di giorni configurato, aggiungi il parametro di query modified_after al tuo feed e includi il tag che inserirà il numero di giorni impostato. Per esempio:

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

Sicurezza #

Consigliamo che il feed JSON accetti solo connessioni SSL criptate e utilizzi autenticazione HTTP se possibile.

Inoltre, dalle impostazioni dell’importatore, puoi attivare Token Authentication. Clerk.io includerà quindi un authorization header in ogni richiesta HTTP che dovrai verificare prima di restituire i dati:

X-Clerk-Authorization: Bearer THE_TOKEN

Puoi verificare il token con una richiesta POST all’endpoint token/verify:

curl -X POST \
  https://api.clerk.io/v2/token/verify \
  -H 'Content-Type: application/json' \
  -d '{"token": "THE_TOKEN", "key": "your_store_public_key"}'

Feed singolo #

Parametri #

Oltre agli oggetti stessi, questo approccio supporta due parametri aggiuntivi:

• created: Unix timestamp che indica quando il feed è stato aggiornato per l’ultima volta. L’importatore di Clerk.io utilizza questo valore per capire se deve recuperare nuovi dati.
• strict: Quando true tutti i dati saranno importati così come sono. Quando false, Clerk.io cercherà di ripulire i dati, ad esempio rimuovendo prodotti o categorie duplicate e convertendo numeri in formato stringa in interi o float.

Esempio di feed #

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

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

Sicurezza #

I tuoi dati sono estremamente sensibili per il business, quindi la sicurezza è la massima priorità!

Consigliamo che il feed JSON accetti solo connessioni criptate SSL e utilizzi l’autenticazione HTTP se possibile.

Inoltre, Clerk prevede un livello aggiuntivo di sicurezza permettendoti di verificare che la richiesta del feed arrivi da una fonte attendibile (cioè noi).

Il sistema si basa su una chiave segreta condivisa: una Private API key che può essere creata in my.clerk.io sotto Developers > API Keys.

Tutte le richieste Clerk.io via HTTP o HTTPS includono due parametri di query hash e salt.

salt è semplicemente una stringa casuale utilizzata per salare la funzione hash, mentre hash è un hash SHA512 calcolato dalla Private API Key come segue:

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

Un esempio di richiesta potrebbe essere il seguente URL:

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

Recuperando i parametri salt e hash dalla richiesta, puoi fare lo stesso calcolo sul tuo server e confrontare i valori hash per confermare che coincidano, il che significa che la richiesta proviene da Clerk.io