Data Feeds

Panoramica #

Indipendentemente dalla tua piattaforma eCommerce, e dal fatto 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 singolo file contenente tutti gli oggetti

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

Tutti i tipi di oggetto 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.

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

Il/i feed devono essere disponibili tramite 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 gestiti sono una causa sicura di errori nel tempo. Se un attributo non esiste per un prodotto, categoria o ordine, semplicemente ometti l’attributo.

Tipi di ID #

Raccomandiamo vivamente di usare interi come ID, ma è anche possibile utilizzare stringhe. Devi sempre utilizzare 1 solo 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 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 un elenco di oggetti, con una serie di campi che ne costituiscono i dati.

Gli oggetti devono contenere almeno i campi richiesti per il tipo di oggetto affinché l’AI di Clerk.io possa funzionare correttamente. Possono opzionalmente contenere qualsiasi attributo aggiuntivo disponibile 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.

Sotto puoi vedere i campi richiesti e i consigliati che sono spesso utilizzati dagli store 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 Indicizzazione #

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

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

Per fare questo, aggiungi lo speciale attributo index: false agli oggetti prodotto che vuoi mantenere senza indicizzazione. Clerk userà poi la cronologia delle loro vendite per mostrare risultati, ma non verranno mai mostrati in nessuna chiamata API.

Per gli altri prodotti, basta omettere l’attributo o impostarlo a index: true.

Categorie #

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

Sotto puoi vedere i campi richiesti e degli esempi di campi opzionali che sono 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 vengono registrati e non sono eliminati quando rimossi dal feed. Devono generalmente essere inviati solo durante la prima importazione e possono poi essere rimossi per risparmiare la capacità del server. Possono essere cancellati tramite la nostra CRUD API.

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

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

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 del cliente o all’ID customer dagli ordini per creare un profilo cliente unico per l’uso con la segmentazione Audience.

Sotto puoi vedere i campi richiesti e degli esempi di campi opzionali spesso usati dagli store 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 sono classificati come prodotto o categoria. Potrebbero essere articoli, post di blog, pagine di atterraggio, pagine brand e altri tipi di contenuti scritti.

Sotto puoi vedere i campi richiesti e degli esempi di campi opzionali spesso usati dagli store 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 Store separati per ogni lingua. Ogni Store può essere configurato con la lingua dei contenuti, il che permette a Search di comprendere meglio la grammatica e gli errori di battitura.

Inoltre, i clienti di diverse regioni o paesi tendono ad avere preferenze e pattern di ricerca differenti, motivo per cui conviene separare anche i dati degli ordini in Store diversi.

Un’alternativa è costruire feed JSON multi-lingua, 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 di lingua anche se il contenuto è lo stesso, per essere sicuri che siano ricercabili per la lingua corretta.

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 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. Al momento 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 in quanto è efficiente per il tuo server e offre il massimo controllo,

Con questo approccio, crei file di feed individuali per ciascun tipo di oggetto. Questo utilizza il metodo di sincronizzazione 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 consente di paginare i risultati programmando il feed in modo che accetti i seguenti parametri di query:

• 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 script feed. Devi semplicemente selezionare quanti oggetti vuoi recuperare per pagina.

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

{{limit}} conterrà il valore che configuri nelle impostazioni dell’importatore. {{offset}} partirà da 0 alla prima chiamata e crescerà continuamente in base a 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 tuo feed restituisce un array vuoto.

URL #

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

Incrementi #

Usando questa funzione, Clerk.io smetterà di cancellare oggetti durante l’importazione, quindi dovrai usare chiamate CRUD API per rimuovere 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 fare questo, assicurati che il tuo feed sia configurato per restituire solo oggetti modificati negli ultimi giorni specificati, quando la richiesta include il parametro di query modified_after.

Quindi, aggiungi 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 aggiorni solo gli oggetti inclusi nei feed.

Per utilizzare il numero di giorni che hai configurato, aggiungi il parametro di query modified_after al tuo feed e includi il tag che inserirà il valore che hai 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 crittografate e, se possibile, utilizzi Autenticazione HTTP.

Inoltre, dalle impostazioni dell’importatore, puoi attivare Token Authentication. Clerk.io includerà quindi un header di autorizzazione su 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"}'

Singolo Feed #

Parametri #

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

• created: Un timestamp unix che indica quando il feed è stato aggiornato l’ultima volta. L’importatore di Clerk.io lo usa per identificare se devono essere recuperati nuovi dati.
• strict: Quando true tutti i dati saranno importati cosi come sono. Quando false Clerk.io tenterà di ripulire i dati, ad esempio rimuovendo prodotti o categorie duplicati 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 è di massima priorità!

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

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

Il sistema si basa su un segreto condiviso; una Private API key che può essere creata 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 è solo una stringa casuale utilizzata per salare la funzione di 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 la seguente URL:

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

Recuperando i parametri salt e hash dalla richiesta puoi eseguire lo stesso calcolo sul tuo server e confrontare i valori degli hash per confermare che coincidano, cioè che la richiesta provenga da Clerk.io