Data Feeds

Panoramica #

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

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

Le due soluzioni utilizzano la stessa struttura dell’oggetto, ma hanno varie funzionalità disponibili per la loro sicurezza e importazione, che sono delineate in questa guida.

Tutti i tipi di oggetti eccetto gli ordini sono specchiati dai feed al database di Clerk.io. Se rimuovi un oggetto dal feed, Clerk.io lo rimuoverà dal database quando verrà importato. Gli ordini sono 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 dovrebbero 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.

Valori Null #

Valori null non controllati sono un modo sicuro per far sì che gli errori si insinuino nel tempo. Se un attributo non esiste per un dato prodotto, categoria o ordine, semplicemente ometti l’attributo.

Tipi di valore ID #

Consigliamo vivamente di utilizzare interi come ID, ma è possibile utilizzare anche stringhe. Devi sempre impegnarti a utilizzare 1 tipo nel tuo feed, il che significa che tutti gli ID per i 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.
Pertanto, 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 un elenco di oggetti, con una serie di campi che compongono i loro dati.

Gli oggetti devono contenere come minimo i campi richiesti per il tipo affinché l’IA di Clerk.io funzioni correttamente, e facoltativamente possono contenere eventuali attributi extra disponibili nella piattaforma eCommerce.

Prodotti #

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

Di seguito puoi vedere i campi richiesti e esempi di quelli facoltativi che sono spesso utilizzati dai negozi eCommerce.

Esempio JSON #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 99995.95,
    "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_names": ["Green","Red"],
    "color_codes": ["#7CFC00","#FF3131"],
    "reviews_amount": 164,
    "reviews_avg": 4.8
  },
  {
    "id": 261,
    "name": "Death Star Deluxe",
    "description": "Death Star - Guaranteed idiot proof",
    "price": 99999999999999.95,
    "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
  }
]

Mantieni i 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 che saranno disponibili per un certo tempo prima di non tornare mai più, è una buona idea mantenere intatta la storia di questi prodotti, in modo che Clerk possa usarla per migliorare i risultati.

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

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

Categorie #

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

Di seguito puoi vedere i campi richiesti e esempi di quelli facoltativi che sono 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 sono registrati e non vengono eliminati quando rimossi dal feed. Devono generalmente essere inviati solo durante il primo import e possono quindi essere rimossi di nuovo per risparmiare capacità del server. Possono essere eliminati tramite la nostra CRUD API.

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

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

Di seguito puoi vedere i campi richiesti e i campi facoltativi. 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 quindi fusi con l’email o l’ID customer dai ordini per creare un singolo profilo cliente da utilizzare con la segmentazione Audience.

Di seguito puoi vedere i campi richiesti e esempi di quelli facoltativi che sono 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 sono classificati come prodotto o categoria. Potrebbe trattarsi di articoli, post di blog, pagine di atterraggio, pagine di marca e altri tipi di contenuti scritti.

Di seguito puoi vedere i campi richiesti e esempi di quelli facoltativi che sono spesso utilizzati dai negozi eCommerce.

Esempio JSON #

[
  {
    "id": 135,
    "type": "cms",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Orari di Apertura",
    "text": "Il testo principale sui nostri orari di apertura..."
 },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Nuovo Post del Blog",
    "text": "Il testo principale sui nostri orari di apertura...",
    "keywords": ["blog", "post", "nuovo"]
 }
]

Multi-lingua #

Clerk.io funziona meglio quando crei negozi separati Stores per ogni lingua. Ogni negozio può essere configurato con la lingua del contenuto, il che rende la ricerca in grado di comprendere molto meglio gli errori di grammatica e ortografia.

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

Un’alternativa a questo è costruire feed JSON multi-lingua, dove tutti gli attributi di testo sono forniti come oggetti con codici lingua come chiavi e le loro traduzioni come valori.

Tutti gli attributi di testo devono avere chiavi di lingua anche se il contenuto al loro interno è lo stesso, per assicurarsi che siano ricercabili per la lingua.

Quando si effettuano chiamate API, includere il parametro language e la chiave di 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_names": ["Green","Red"],
    "color_codes": ["#7CFC00","#FF3131"],
    "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. Se la tua lingua non è nell’elenco sottostante, scegli una lingua che utilizza la stessa radice, o semplicemente “english”. Funzionerà comunque, ma la neutralizzazione grammaticale nella ricerca sarà meno efficace.

• danese
• olandese
• inglese
• finlandese
• francese
• tedesco
• italiano
• norvegese
• portoghese
• russo
• spagnolo
• svedese

Feed Multipli #

Questo è l’approccio consigliato in quanto è efficiente per il tuo server e offre il massimo controllo.

Con questo approccio, crei file di feed individuali per ciascuno dei tuoi oggetti. Questo utilizza il metodo di sincronizzazione chiamato Clerk.io JSON Feed V2.

Questi supportano content-type: application/x-ndjson o application/json.

Ogni feed dovrebbe 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 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 tuo codice feed. Devi semplicemente selezionare la quantità di oggetti che desideri recuperare per pagina.

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

{{limit}} conterrà il numero che configuri nelle impostazioni dell’importatore. {{offset}} inizierà da 0 nella prima chiamata e crescerà continuamente 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 arresto è quando il tuo feed restituisce un array vuoto.

URL #

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

Incrementi #

Utilizzare questa funzionalità significa che Clerk.io smetterà di eliminare oggetti durante l’importazione, quindi è necessario utilizzare CRUD API calls 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 numero scelto di giorni, piuttosto che inviare tutti i dati ogni volta.

Per fare ciò, inizia assicurandoti 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.

Quindi, aggiungi un numero di giorni nel campo etichettato Incremental time {{modified_after}} trovato 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 numero di giorni che hai configurato. Ad esempio:

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

Sicurezza #

Consigliamo che il feed JSON accetti solo una connessione crittografata SSL e utilizzi HTTP Authentication se possibile.

Inoltre, dalle impostazioni dell’importatore, puoi attivare Token Authentication. Clerk.io includerà quindi un header di autorizzazione 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 di quando il feed è stato aggiornato l’ultima volta. L’importatore di Clerk.io utilizza questo per identificare se devono essere recuperati nuovi dati.
• strict: Quando true tutti i dati verranno importati così 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à!

Consigliamo che il feed JSON accetti solo una connessione crittografata SSL e utilizzi HTTP Authentication se possibile.

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 chiave API privata che può essere creata in my.clerk.io sotto Settings > API Keys.

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

salt è semplicemente una stringa casuale utilizzata per salare la funzione hash mentre hash è un hash SHA512 calcolato dalla chiave API privata nel seguente modo:

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