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 variazioni dei feed:

• Più file per oggetti diversi
• Un solo file contenente tutti gli oggetti

Le due soluzioni utilizzano la stessa struttura degli oggetti, ma hanno diverse funzionalità disponibili per proteggere e importarli, che sono descritte in questa guida.

Tutti i tipi di oggetto tranne gli ordini vengono rispecchiati dai feed al 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 rimangono 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 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 far emergere 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 scegliere un solo tipo nel tuo feed, ovvero 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 underscores.
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, ciascuno con una serie di campi che compongono i loro dati.

Gli oggetti devono contenere almeno i campi obbligatori per il tipo affinché l’intelligenza artificiale di Clerk.io funzioni correttamente; in aggiunta possono contenere attributi extra disponibili nella piattaforma eCommerce.

Prodotti #

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

Sotto puoi vedere i campi obbligatori e quelli consigliati 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 Prodotti Senza Indicizzazione #

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

Se vendi biglietti o oggetti usati disponibili solo temporaneamente, è una buona idea mantenere la cronologia di questi prodotti intatta, così Clerk può utilizzarla per migliorare i risultati.

Per fare questo, aggiungi l’attributo speciale index: false agli oggetti prodotto che dovrebbero essere mantenuti senza essere indicizzati. Clerk utilizzerà così la cronologia delle loro vendite per mostrare risultati, ma non verranno mai visualizzati in alcuna chiamata API.

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

Categorie #

Ogni oggetto rappresenta una singola categoria. Clerk.io costruisce una gerarchia interna delle categorie in base alle sottocategorie fornite per ogni categoria.

Sotto puoi vedere i campi obbligatori ed esempi di campi opzionali utilizzati spesso 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 se rimossi dal feed. Generalmente vanno inviati solo durante la prima importazione e possono poi essere rimossi per risparmiare risorse server. Possono essere eliminati tramite la nostra CRUD API.

I dati parcels possono essere sincronizzati attualmente 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 negli ordini per analizzare il comportamento dei clienti e identificare i trend. Insieme ai products, è il tipo di oggetto più importante.

Sotto puoi vedere i campi obbligatori e quelli 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 degli ordini, per creare un unico profilo utilizzato per la segmentazione Audience.

Sotto puoi vedere i campi obbligatori e alcuni esempi di campi opzionali spesso utilizzati 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 tipi di contenuto eCommerce che non sono classificati come prodotto o categoria. Possono essere articoli, post di blog, landing page, pagine brand e altri tipi di contenuto scritto.

Sotto puoi vedere i campi obbligatori ed 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"]
 }
]

Multilingua #

Clerk.io funziona al meglio quando crei Store separati per ciascuna lingua. Ogni Store può essere configurato con la lingua del contenuto, permettendo a Search di capire molto meglio grammatica e errori di ortografia.

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

Un’alternativa a ciò è costruire feed JSON multilingua, dove tutti gli attributi testuali vengono forniti come oggetti con i codici lingua come chiavi e le traduzioni come valori.

Tutti gli attributi di testo devono avere le chiavi lingua anche se il contenuto è uguale, per permettere che siano ricercabili per quella lingua.

Quando effettui chiamate API, includi il parametro language e il codice lingua corrispondente, per ottenere i dati corretti.

Esempio Multi-lingua JSON #

[
  {
    "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 è nell’elenco, scegli una lingua affine o semplicemente “english”. Funzionerà comunque, ma la normalizzazione 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 perché è efficiente per il server e offre il massimo controllo.

Con questo approccio, crei file di feed individuali per ciascun tipo di oggetto. Utilizza il metodo 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 codificando 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 solo selezionare la quantità di oggetti da recuperare per pagina.

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

{{limit}} conterrà il numero che hai configurato nelle impostazioni dell’importatore. {{offset}} inizierà da 0 nella prima chiamata e crescerà progressivamente 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 #

L’utilizzo di questa funzione significa che Clerk.io smetterà di eliminare oggetti durante l’importazione, quindi dovrai usare chiamate API CRUD per rimuovere oggetti dal database 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 gli oggetti modificati in una determinata quantità di giorni, quando la richiesta include il parametro di query modified_after.

Poi, aggiungi il numero di giorni nel campo Incremental time {{modified_after}} che trovi nelle impostazioni dell’importatore su 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 usare il numero di giorni che hai configurato, aggiungi il parametro di query modified_after al tuo feed e includi il tag che inserirà questo numero. 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 cifrate SSL e, se possibile, utilizzi Autenticazione HTTP.

Inoltre, dalle impostazioni dell’importatore, puoi attivare Token Authentication. Clerk.io includerà quindi un authorisation header su ogni richiesta HTTP, che devi 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: Un timestamp unix che indica la data di aggiornamento del feed. L’importatore di Clerk.io lo utilizza per capire se sono presenti nuovi dati da importare.
• strict: Quando è true tutti i dati vengono importati così come sono. Se è false, Clerk.io proverà a pulire i dati, ad esempio eliminando prodotti o categorie duplicati e convertendo i 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 del business, quindi la sicurezza è di massima priorità!

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

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

Il sistema si basa su una chiave segreta condivisa; una chiave API privata che può essere creata su 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 per salare la funzione hash mentre hash è un hash SHA512 calcolato dalla chiave privata nel modo seguente:

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

Una richiesta di esempio potrebbe essere il seguente URL:

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

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