Data Feeds

Panoramica #

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

Supportiamo due diverse varianti di feed:

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

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

Tutti i tipi di oggetto eccetto gli ordini vengono copiati dal feed al database di Clerk.io. Se rimuovi un oggetto dal feed, Clerk.io lo rimuoverà anche dal database quando viene importato. Gli ordini vengono registrati e mantenuti nel database.

Si consiglia 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 devono essere disponibili a 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 (object).

Valori Null #

Valori null non controllati sono una fonte certa di errori col passare del tempo. Se un attributo non esiste per un determinato prodotto, categoria o ordine, semplicemente ometti l’attributo.

Tipi di valore ID #

Consigliamo fortemente di utilizzare interi come ID, ma è possibile usare anche stringhe. Tuttavia, devi sempre scegliere un solo tipo nel tuo feed: tutti gli ID dei tuoi oggetti devono essere dello stesso tipo.

Nomi degli attributi #

Gli attributi di oggetto possono contenere solo valori alfanumerici (A-Z, 0-9) e underscore.
Quindi, un nome valido per un attributo 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 costituiscono i loro dati.

Gli oggetti devono contenere almeno i campi obbligatori per il tipo specifico, affinché l’AI di Clerk.io funzioni correttamente; facoltativamente possono includere tutti gli attributi disponibili nella piattaforma eCommerce.

Prodotti #

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

Di seguito sono riportati i campi obbligatori e alcuni esempi di campi facoltativi spesso 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
  }
]

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 articoli usati disponibili per un tempo limitato, è una buona prassi mantenere la cronologia di questi prodotti, così Clerk potrà usarla per migliorare i risultati.

Per fare questo, aggiungi l’attributo speciale index: false agli oggetti prodotto che vuoi mantenere senza indicizzarli. Clerk userà comunque la cronologia delle loro vendite per i risultati, ma non verranno mai mostrati tramite le chiamate API.

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

Categorie #

Ogni oggetto rappresenta una singola categoria. Clerk.io costruisce un albero di categorie interno in base alle sottocategorie indicate per ciascuna categoria.

Qui sotto trovi i campi obbligatori e alcuni esempi opzionali spesso 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 vengono registrati e non eliminati quando rimossi dal feed. Generalmente devono essere inviati solo durante la prima importazione e possono quindi essere rimossi per risparmiare risorse server. Possono essere eliminati tramite la nostra CRUD API.

I dati parcels 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/ID cliente contenuti negli ordini per analizzare il comportamento dei clienti e identificare tendenze. Insieme a products, è il tipo di oggetto più importante.

Di seguito 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 tramite l’email o l’ID customer dagli ordini per creare un profilo cliente unico, utile per la segmentazione con Audience.

Qui sotto trovi i campi obbligatori e alcuni facoltativi comunemente 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 in genere qualsiasi contenuto eCommerce che non sia classificato come prodotto o categoria. Potrebbe trattarsi di articoli, post del blog, landing page, pagine brand e altri tipi di contenuto testuale.

Qui sotto sono riportati i campi obbligatori e alcuni esempi opzionali spesso 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"]
 }
]

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 meglio grammatica ed errori di ortografia.

Inoltre, i clienti di diverse regioni o paesi tendono ad avere preferenze e schemi di ricerca differenti, il che significa che funziona meglio separare anche i dati ordine in Store diversi.

In alternativa, è possibile costruire feed JSON multi-lingua, dove tutti gli attributi testuali vengono forniti come oggetti con i codici lingua come chiavi e le rispettive traduzioni come valori.

Tutti gli attributi testuali devono avere le chiavi di lingua anche se il contenuto è identico, per garantire la ricercabilità nella lingua scelta.

Quando effettui chiamate API, includi il parametro language e la relativa chiave lingua per recuperare i dati nella lingua corretta.

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 col suo nome esatto. Attualmente supportiamo 54 lingue. Se la tua lingua non è nell’elenco qui sotto, scegli una lingua simile 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, crei file di feed individuali per ciascun oggetto. Utilizza il metodo di sync chiamato Clerk.io JSON Feed V2.

Questi supportano 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:

• limit: 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 tuo codice feed. Devi solo scegliere quanti oggetti vuoi recuperare per pagina.

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

{{limit}} conterrà il valore impostato 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 stop è quando il feed restituisce un array vuoto.

URL #

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

Incremente #

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

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

Per farlo, assicurati innanzitutto che il tuo feed sia configurato per restituire solo gli oggetti modificati in un certo numero di giorni, quando la richiesta include il parametro modified_after.

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

In questo modo l’importatore di Clerk.io manterrà tutti i dati nel database e aggiornerà solo gli oggetti inclusi nei feed.

Per usare il numero di giorni configurato, aggiungi il parametro modified_after al feed e inserisci il tag relativo. Ad 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 usi autenticazione HTTP se possibile.

Inoltre, tramite le 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 unico #

Parametri #

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

• created: Il timestamp unix di quando il feed è stato aggiornato l’ultima volta. L’importatore di Clerk.io usa questo valore per identificare se ci sono nuovi dati da importare.
• strict: Se impostato su true, tutti i dati verranno importati come sono. Se impostato su false, Clerk.io proverà a normalizzare i dati (ad esempio rimuovendo prodotti/categorie duplicati, 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 dal punto di vista business, quindi la sicurezza è una priorità assoluta!

Consigliamo che il feed JSON accetti solo connessioni SSL criptate e usi autenticazione HTTP dove possibile.

Inoltre, Clerk fornisce un ulteriore livello di sicurezza che ti permette di verificare che la richiesta di feed provenga da una fonte attendibile (cioè da noi).

Il sistema è basato su una chiave privata condivisa (Private API key) che puoi generare su my.clerk.io sotto Developers > API Keys.

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

salt è una stringa casuale utilizzata per saltare la funzione hash, mentre hash è un hash SHA512 calcolato dalla Private API Key nel seguente modo:

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

Un esempio di richiesta potrebbe essere la seguente:

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; se coincidono la richiesta proviene da Clerk.io