Data Feeds

Panoramica #

Indipendentemente dalla tua piattaforma eCommerce, e che sia presente 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:

• File multipli per oggetti diversi
• Un unico file contenente tutti gli oggetti

Le due soluzioni utilizzano la stessa struttura degli oggetti, ma presentano varie funzionalità per la sicurezza e l’importazione, descritte in questa guida.

Tutti i tipi di oggetti tranne gli ordini vengono copiati dai feed nel database di Clerk.io. Se rimuovi un oggetto dal feed, Clerk.io lo rimuoverà dal database al momento dell’importazione. Gli ordini vengono registrati e mantenuti nel database.

Consigliamo di generare il/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.

Il/i feed deve/devono essere disponibili a un URL accessibile dai server di Clerk.io.

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

Tipi di dati #

Supportiamo attributi dei tipi: int, float, str, array, bool, dict (object).

Valori null #

Valori null non controllati sono un modo sicuro per introdurre errori nel tempo. Se un attributo non esiste per un determinato prodotto, categoria o ordine basta omettere l’attributo.

Tipi di valore ID #

Consigliamo vivamente di utilizzare interi come ID ma è possibile utilizzare anche stringhe. È necessario mantenere sempre lo stesso tipo nel tuo feed, cioè tutti gli ID dei tuoi oggetti devono essere dello stesso tipo.

Nomi degli attributi #

Gli attributi degli oggetti possono contenere solo valori alfanumerici (A-Z, 0-9) e underscore.
Quindi, un nome attributo valido potrebbe 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 in fase di sincronizzazione.

Struttura degli oggetti #

I feed JSON sono costituiti da una lista di oggetti, con una serie di campi che compongono i loro dati.

Gli oggetti devono contenere come minimo i campi obbligatori per il tipo in modo che l’AI di Clerk.io funzioni correttamente, e opzionalmente possono contenere attributi extra disponibili nella piattaforma eCommerce.

Prodotti #

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

Qui sotto puoi vedere i campi obbligatori e quelli raccomandati più spesso usati dai negozi 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
  }
]

Mantenere prodotti senza indicizzazione #

Per alcune configurazioni, potresti voler mantenere i prodotti nel database di Clerk.io senza mostrarli in alcun risultato.

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

Per farlo, aggiungi l’attributo speciale index: false agli oggetti prodotto che devono essere mantenuti senza essere indicizzati. Clerk userà quindi la cronologia delle loro vendite, ma non saranno mai mostrati in nessuna chiamata API.

Per gli altri prodotti, semplicemente lascia l’attributo fuori o impostalo su index: true.

Categorie #

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

Qui sotto puoi vedere i campi obbligatori ed esempi di campi opzionali spesso usati dagli store 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 quando rimossi dal feed. Di norma devono essere inviati solo durante la prima importazione e possono poi essere rimossi per risparmiare capacità server. Possono essere eliminati tramite la nostra CRUD API.

Ogni oggetto rappresenta un singolo ordine. Clerk.io utilizza gli ID prodotto e l’indirizzo email/ID cliente dei dettagli ordine per analizzare il comportamento dei clienti e individuare trend. Insieme a products, è il tipo di oggetto più importante.

Qui sotto puoi vedere i campi obbligatori e opzionali. Per includere i dati del pacco, aggiungi un array tracking all’ordine. Non inviare i pacchi come oggetto di primo livello separato.

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

Clienti #

Ogni oggetto rappresenta un singolo Cliente. Gli attributi forniti vengono poi uniti all’email o all’ID customer dell’ordine per creare un unico profilo cliente per la segmentazione con Audience.

Qui sotto puoi vedere i campi obbligatori ed esempi di opzionali spesso 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 rappresentano generalmente tutti quei contenuti eCommerce che non sono classificati come prodotto o categoria. Può trattarsi di articoli, post del blog, landing page, pagine brand e altri tipi di contenuti scritti.

Qui sotto puoi vedere i campi obbligatori ed esempi di opzionali utilizzati spesso 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"]
 }
]

Multi-lingua #

Clerk.io funziona meglio quando crei Store separati per ogni lingua. Ogni Store può essere configurato con la lingua dei contenuti, così da far capire a Search grammatica ed errori di ortografia con maggiore efficacia.

Inoltre, clienti da regioni o paesi diversi tendono ad avere preferenze e pattern di ricerca differenti, quindi conviene separare anche i dati ordine in Store distinti.

Un’alternativa è creare feed multi-lingua JSON, dove tutti gli attributi testuali sono forniti come oggetti con codici lingua come chiavi, e le relative traduzioni come valori.

Tutti gli attributi testuali devono avere le chiavi lingua anche se il contenuto interno è lo stesso, per garantirne la ricercabilità.

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

Esempio JSON Multi-lingua #

[
  {
    "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 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 è in elenco, scegli una lingua affine 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 consigliato in quanto efficiente per il tuo server e offre il massimo controllo.

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

Questi supportano i 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 funzione opzionale che ti permette di paginare i risultati codificando il tuo feed per accettare i seguenti parametri:

• limit: Il numero di oggetti da restituire per pagina.
• offset: L’indice del primo oggetto da restituire in una pagina.

L’importatore di Clerk.io può essere configurato per inviare questi parametri al codice feed. Devi solo selezionare la quantità di oggetti che vuoi recuperare per pagina.

Quando configuri il tuo feed URL, puoi quindi usare {{limit}} e {{offset}} per aggiungere i dati come query parameter.

{{limit}} conterrà il valore scelto nelle impostazioni dell’importatore. {{offset}} partirà da 0 nella prima chiamata, e crescerà progressivamente in base al limit.

Ad es.

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

La condizione di stop è quando il feed restituisce un array vuoto.

URL #

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

Incrementi #

Utilizzare questa funzione fa sì che Clerk.io smetta di eliminare oggetti durante l’importazione, quindi dovrai utilizzare chiamate CRUD API per rimuovere oggetti dal database di Clerk.io.

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

Per fare questo, assicurati che il tuo feed sia configurato per restituire solo oggetti modificati negli ultimi X giorni, quando la richiesta include il parametro modified_after.

Poi, aggiungi il numero di giorni nel campo contrassegnato come Incremental time {{modified_after}} che trovi nelle impostazioni dell’importatore di Clerk.io.

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

Per utilizzare il numero di giorni configurato, aggiungi il parametro modified_after alla query del feed e il tag che inserirà il numero di giorni configurato. Ad esempio:

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

Sicurezza #

Raccomandiamo che il feed JSON accetti solo connessioni SSL e, se possibile, utilizzi autenticazione HTTP.

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

X-Clerk-Authorization: Bearer THE_TOKEN

Puoi verificare il token tramite 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 unico #

Con questo approccio, raggruppi tutti i tuoi oggetti in un unico file JSON. Questo utilizza il metodo di sincronizzazione chiamato Clerk.io JSON Feed.

Parametri #

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

• created: Unix timestamp dell’ultimo aggiornamento del feed. L’importatore di Clerk.io lo usa per capire se devono essere recuperati nuovi dati.
• strict: Quando impostato a true tutti i dati saranno importati così come sono. Se è false Clerk.io proverà a ripulire i dati, ad esempio rimuovendo prodotti o categorie duplicati, e convertendo numeri stringa in interi o float.

Esempio Feed #

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

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

Sicurezza #

I tuoi dati sono estremamente sensibili dal punto di vista business, quindi la sicurezza ha la priorità più alta!

Raccomandiamo che il feed JSON accetti solo una connessione SSL e, quando possibile, utilizzi autenticazione HTTP.

Inoltre, Clerk offre un ulteriore livello di sicurezza per garantirti che la richiesta al feed venga da una fonte autorizzata (cioè da noi).

Il sistema si basa su un segreto condiviso; una API key privata che può essere creata su my.clerk.io alla voce Developers > API Keys.

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

salt è semplicemente una stringa casuale usata per salare la funzione hash, mentre hash è uno SHA512 generato dalla API Key privata così:

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

Un esempio di richiesta potrebbe essere la seguente URL:

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

Recuperando sia il parametro salt sia hash dalla richiesta, puoi fare lo stesso calcolo sul tuo server e confrontare i valori di hash per confermare che siano gli stessi, quindi che la richiesta venga effettivamente da Clerk.io