Data Feeds

Panoramica #

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

Supportiamo due diverse varianti dei feed:

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

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

Tutti i tipi di oggetto eccetto gli ordini vengono rispecchiati 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.

Raccomandiamo 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 dovrebbero essere disponibili su 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 (oggetto).

Valori nulli #

Valori null non controllati sono un modo sicuro in cui si possano insinuare errori nel tempo. Se un attributo non esiste per un determinato prodotto, categoria o ordine, basta semplicemente omettere l’attributo.

Tipi di valori ID #

Raccomandiamo vivamente di utilizzare interi come ID ma è anche possibile utilizzare stringhe. Devi sempre mantenere un solo tipo nel tuo feed, il che significa che 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 di 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 nella sincronizzazione.

Struttura degli Oggetti #

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

Gli oggetti devono contenere almeno i campi richiesti per il tipo, affinché l’AI di Clerk.io funzioni correttamente, e opzionalmente possono contenere qualsiasi altro attributo disponibile nella piattaforma eCommerce.

Prodotti #

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

Di seguito puoi vedere i campi richiesti e alcuni esempi di campi opzionali spesso utilizzati 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 i Prodotti senza indicizzarli #

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

Se vendi biglietti o usato che saranno disponibili per un periodo prima di scomparire definitivamente, è una buona idea mantenere la cronologia di questi prodotti intatta, così Clerk potrà usarla per migliorare i risultati.

Per fare ciò, aggiungi l’attributo speciale index: false agli oggetti prodotto che devono essere mantenuti senza essere indicizzati. Clerk userà quindi la cronologia delle loro vendite per mostrare i risultati, ma non verranno mai mostrati in nessuna chiamata API.

Per tutti gli altri prodotti, basta non inserire l’attributo o impostarlo su index: true.

Categorie #

Ogni oggetto rappresenta una singola categoria. Clerk.io costruisce una struttura ad albero interna delle categorie in base alle sottocategorie fornite per ciascuna categoria.

Di seguito puoi vedere i campi richiesti e alcuni esempi di campi opzionali spesso utilizzati dai negozi 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 vengono registrati e non vengono eliminati quando 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 nostra CRUD API.

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

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

Di seguito puoi vedere i campi richiesti 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 all’email del cliente o all’ID customer dagli ordini per creare un unico profilo cliente da utilizzare per la segmentazione Audience.

Di seguito puoi vedere i campi richiesti e alcuni esempi di campi opzionali spesso utilizzati dai negozi 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 contenuto eCommerce che non rientrano tra i prodotti o le categorie. Potrebbero essere articoli, blog, landing page, pagine brand e altri tipi di contenuti scritti.

Di seguito puoi vedere i campi richiesti e alcuni esempi di campi opzionali spesso utilizzati dai negozi 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 al meglio quando crei Stores separati per ogni lingua. Ogni Store può essere configurato con la lingua del contenuto, il che permette a Search di comprendere molto meglio la grammatica e gli errori di ortografia.

Inoltre, clienti di diverse regioni o paesi tendono ad avere preferenze e modelli di ricerca differenti, il che significa che è meglio separare i dati degli ordini in Stores diversi.

Un’alternativa è costruire feed JSON multi-lingua, in cui tutti gli attributi testuali sono forniti come oggetti con il codice lingua come chiave e la traduzione come valore.

Tutti gli attributi di tipo testo devono avere chiavi lingua anche se il contenuto è identico, per garantirne la ricerca nella lingua.

Quando effettui chiamate API, includi il parametro language e la chiave lingua corrispondente per ottenere 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 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 suo nome esatto. Attualmente supportiamo 54 lingue. Se la tua lingua non è nella lista qui sotto, scegli una lingua correlata o semplicemente “english”. Funzionerà comunque, ma la neutralizzazione della grammatica 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 metodo, costruisci file feed separati per ciascuno dei tuoi oggetti. 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 consente di paginare i risultati programmando il tuo feed per accettare i seguenti parametri di query:

• 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 del tuo feed. Devi semplicemente selezionare il numero di oggetti che desideri recuperare 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 configurato nelle impostazioni dell’importatore. {{offset}} partirà da 0 nella prima chiamata, e crescerà continuamente in base a limit.

Es.

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

La condizione di arresto è quando il tuo feed restituisce un’array vuoto.

URL #

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

Incrementi #

Utilizzare questa funzione significa che Clerk.io smetterà di eliminare oggetti durante l’importazione, quindi dovrai usare le chiamate CRUD API per rimuovere oggetti dal database di Clerk.io.

La soluzione multi-feed supporta l’opzione opzionale di inviare solo i dati che sono cambiati da un determinato numero di giorni, invece di inviare tutti i dati ogni volta.

Per fare ciò, accertati innanzitutto che il tuo feed sia configurato per restituire solo oggetti che sono stati modificati in un determinato numero di giorni quando la richiesta include il parametro di query modified_after.

Poi, inserisci un numero di giorni nel campo 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 aggiornerà solo gli oggetti inclusi nei feed.

Per utilizzare 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 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 una connessione SSL criptata e utilizzi l’Autenticazione HTTP se possibile.

Inoltre, nelle impostazioni dell’importatore, puoi attivare Token Authentication. Clerk.io includerà quindi un authorisation 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 metodo supporta due parametri aggiuntivi:

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

Esempio Feed #

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

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

Sicurezza #

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

Raccomandiamo che il feed JSON accetti solo una connessione SSL criptata e utilizzi Autenticazione HTTP se possibile.

Inoltre, Clerk offre un ulteriore livello di sicurezza consentendoti di verificare che la richiesta al feed provenga 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 in Developers > API Keys.

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

salt è semplicemente una stringa casuale usata per salare la funzione di hash, mentre hash è una SHA512 hash calcolata dalla Private API Key nel seguente modo:

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 sia i parametri salt che hash dalla richiesta, puoi effettuare lo stesso calcolo sul tuo server e confrontare i valori di hash per confermare che coincidano, il che significa che la richiesta proviene da Clerk.io