Formato e requisiti del catalogo

Definizione

Un catalogo prodotti rappresenta l'intera collezione di prodotti disponibili per l'acquisto su un negozio e-commerce.

Ogni elemento del catalogo è rappresentato come un oggetto JSON con la seguente struttura:

{
  "id": "805371A",
  "itemGroupId": "805371",
  "categoryHierarchies": [
    { "categories": ["Women", "Shoes"] },
    { "categories": ["Sports & Fitness", "Shoes"] }
  ],
  "title": "Red Shoes",
  "description": "Fancy red shoes",
  "brand": "Designer Brand",
  "languageCode": "en",
  "productMetadata": {
    "stockState": "IN_STOCK",
    "availableQuantity": 30,
    "exactPrice": {
      "originalPrice": 119.99,
      "displayPrice": 89.99
    },
    "currencyCode": "USD",
    "canonicalProductUri": "https://www.store.com/shoes/red-shoes",
    "images": [
      {
        "uri": "https://www.store.com/images/805371.jpg",
        "width": 500,
        "height": 500
      }
    ]
  }
}

Nota: L'esempio precedente include interruzioni di riga per leggibilità, tuttavia il file di catalogo che crei deve includere un elemento di catalogo codificato JSON per riga. Il file deve anche essere codificato in UTF-8.

{"id":"805371","categoryHierarchies":[{"categories":["Women","Shoes"]}],"title":"Red Shoes","description":"Fancy red shoes","languageCode":"en","productMetadata":{"exactPrice":{"originalPrice":119.99,"displayPrice":89.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/red-shoes","images":[{"uri":"https://www.store.com/images/805371.jpg","width":500,"height":500}]}}
{"id":"805372","categoryHierarchies":[{"categories":["Women","Shoes"]}],"title":"Green Shoes","description":"Fancy green shoes","languageCode":"en","productMetadata":{"exactPrice":{"originalPrice":148.99,"displayPrice":129.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/green-shoes","images":[{"uri":"https://www.store.com/images/805372.jpg","width":500,"height":500}]}}

Proprietà

id

• Tipo: Stringa
• Obbligatorio
• Dimensione massima: 128 byte

Questo ID deve essere unico tra tutti gli elementi del catalogo all'interno dello stesso catalogo. Deve essere lo stesso ID tracciato con le visualizzazioni delle pagine prodotto nella tua integrazione Fanplayr.

itemGroupId

• Tipo: Stringa
• Obbligatorio (a seconda della configurazione del livello del catalogo)
• Dimensione massima: 128 byte

Identificatore del gruppo di varianti di prodotto, noto anche come identificatore del prodotto "master". Questo collega tutte le varianti di prodotto correlate per i risultati della previsione.

O tutti gli elementi del tuo catalogo devono avere un valore per itemGroupId oppure nessuno di essi può averlo. Non è possibile importare dati di catalogo con itemGroupId impostato per alcuni elementi ma non per altri. Questo campo è obbligatorio quando si utilizzano i livelli di catalogo Master/Master o Variant/Master livello del catalogo.

categoryHierarchies

• Tipo: Array
• Obbligatorio (è richiesta almeno una voce di gerarchia di categoria)
• Dimensione massima: 1000 byte (se codificato come JSON)

Categorie dell'elemento del catalogo. Questo campo è ripetuto per supportare un elemento di catalogo appartenente a diverse gerarchie di categorie parallele. Deve essere presente almeno una categoria.

Ad esempio, se un prodotto di scarpe appartiene sia a Donne > Scarpe che a Sport e Fitness > Scarpe, potrebbe essere rappresentato come:

"categoryHierarchies": [
  { "categories": ["Women", "Shoes"] },
  { "categories": ["Sports & Fitness", "Shoes"] }
]

title

• Tipo: Stringa
• Obbligatorio
• Dimensione massima: 500 byte

Titolo dell'elemento del catalogo.

description

• Tipo: Stringa
• Dimensione massima: 500 byte

Descrizione dell'elemento del catalogo. Questo valore non può essere visualizzato nei widget ma può aiutare a migliorare il modello di raccomandazione.

brand

• Tipo: Stringa
• Dimensione massima: 100 byte

Il marchio o il produttore associato al prodotto.

languageCode

• Tipo: Stringa
• Obbligatorio

La lingua del titolo/descrizione. Utilizzare i tag di lingua definiti da BCP 47. https://www.rfc-editor.org/rfc/bcp/bcp47.txt. I nostri codici lingua supportati includono "en", "es", "fr", "de", "ar", "fa", "zh", "ja", "ko", "sv", "ro", "nl".

productMetadata

• Tipo: Oggetto
• Obbligatorio

Contiene le proprietà stockState, availableQuantity, exactPrice, currencyCode, canonicalProductUri e images.

stockState

• Tipo: ENUM
• Annidato sotto: productMetadata
• Obbligatorio

Deve essere uguale a uno dei seguenti valori:

• IN_STOCK - Articolo disponibile.
• OUT_OF_STOCK - Articolo esaurito.
• PREORDER - Articolo in stato di preordine.
• BACKORDER - Articolo in arretrato (es. temporaneamente esaurito).

availableQuantity

• Tipo: Numero
• Annidato sotto: productMetadata

La quantità rimanente dell'articolo disponibile per l'acquisto.

exactPrice

• Tipo: Oggetto
• Obbligatorio:

Contiene le proprietà originalPrice e displayPrice.

originalPrice

• Tipo: Float
• Annidato sotto: productMetadata.exactPrice
• Obbligatorio

Il prezzo originale dell'articolo prima degli sconti, come i prezzi di vendita.

displayPrice

• Tipo: Float
• Annidato sotto: productMetadata.exactPrice
• Obbligatorio

Il prezzo attuale dell'articolo dopo gli sconti, come i prezzi di vendita.

currencyCode

• Tipo: Stringa
• Obbligatorio

Il codice valuta per i prezzi degli articoli. Utilizzare il codice ISO-4217 di tre caratteri.

canonicalProductUri

• Tipo: Stringa
• Obbligatorio

L'URI di base del prodotto. Se il tuo prodotto ha URI diversi per colori o dimensioni diverse, se possibile fornisci l'URI che punta al prodotto di base senza varianti.

images

• Tipo: Array
• Obbligatorio (è richiesta almeno un'immagine)

Un array di immagini del prodotto. Solo la prima immagine viene visualizzata nel componente Raccomandazione. È richiesta almeno un'immagine.

Ogni immagine dovrebbe essere un oggetto con la seguente struttura:

{
  // Obbligatorio. URL dell'immagine.
  // Dimensione massima: 1000 byte
  "uri": "https://www.store.com/images/805371.jpg",
  // Opzionale. Larghezza dell'immagine in pixel.
  "width": 500,
  // Opzionale. Altezza dell'immagine in pixel.
  "height": 500
}

tags

• Tipo: Array di Stringa
• Dimensione massima: 500 byte (combinati)

Tag opzionali da associare all'elemento del catalogo. Ciascuno dovrebbe essere una stringa codificata UTF-8. La lunghezza totale di tutti i tag per un singolo elemento del catalogo non deve superare i 500 byte.

itemAttributes

• Tipo: Oggetto
• Dimensione massima: 1000 byte (combinati)

Opzionale. Attributi aggiuntivi dell'elemento da includere nel modello di raccomandazione. Ad esempio, per i prodotti al dettaglio questo potrebbe includere lo stile del prodotto, il colore, ecc. Questi attributi possono aggiungere segnali aggiuntivi per i modelli di raccomandazione.

Gli attributi dell'elemento devono essere divisi in set categorici e numerici con la seguente struttura:

"itemAttributes": {
  "categoricalFeatures": {
    "colors": {
      "value": ["red", "blue"]
    },
    "sizes": {
      "value": ["S", "M", "L"]
    }
  },
  "numericalFeatures": {
    "lengths_cm": {
      "value": [2.3, 15.4]
    },
    "heights_cm": {
      "value":[8.1, 6.4]
    }
  }
}

Formato del file di catalogo

Il formato del file di catalogo prodotti ha i seguenti requisiti:

• Ogni elemento del catalogo deve essere formattato utilizzando la struttura JSON descritta sopra.
• Ogni elemento del catalogo deve essere contenuto su una singola riga.
• La dimensione totale del file di catalogo non deve superare i 50 MB non compressi. Se il tuo catalogo supera questa dimensione, puoi dividerlo e importarlo più volte.
• Tutti gli articoli devono utilizzare la stessa lingua e valuta. Non è possibile mescolare lingue e valute diverse nello stesso catalogo a causa delle limitazioni nella formazione dei modelli di intelligenza artificiale. Sarà necessario gestire cataloghi e progetti separati se il tuo negozio e-commerce contiene più visualizzazioni del negozio con lingue e/o valute diverse.

Di seguito è riportato un esempio di file di catalogo con 2 articoli:

{"id":"PRODUCT_1","categoryHierarchies":[{"categories":["Women","Shoes"]},{"categories":["Sports & Fitness","Shoes"]}],"title":"Red Shoes","description":"Fancy red shoes","languageCode":"en","productMetadata":{"stockState":"IN_STOCK","availableQuantity":30,"exactPrice":{"originalPrice":119.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/red-shoes","images":[{"uri":"https://www.store.com/images/PRODUCT_1.jpg","width":500,"height":500}]}}
{"id":"PRODUCT_2","categoryHierarchies":[{"categories":["Men","Shoes"]},{"categories":["Sports & Fitness","Shoes"]}],"title":"Blue Shoes","description":"Fast blue shoes","languageCode":"en","productMetadata":{"stockState":"IN_STOCK","availableQuantity":17,"exactPrice":{"originalPrice":119.99},"currencyCode":"USD","canonicalProductUri":"https://www.store.com/shoes/blue-shoes","images":[{"uri":"https://www.store.com/images/PRODUCT_2.jpg","width":500,"height":500}]}}

Livelli del catalogo

Prima di importare il tuo catalogo per la prima volta, devi determinare se desideri tracciare gli articoli master o le varianti con i tuoi eventi utente sul sito, e se desideri che gli articoli master o le varianti vengano restituiti con le tue previsioni. Fanplayr ti assisterà nella configurazione della tua integrazione.

Gli articoli master rappresentano un gruppo di articoli simili (in altre parole, un gruppo SKU). Un esempio di articolo master potrebbe essere "Maglietta con scollo a V", con varianti come "Maglietta con scollo a V marrone, taglia XL" e "Maglietta con scollo a V bianca, taglia S". I master e le varianti sono talvolta descritti come articoli "genitore" e "figlio".

Le possibili combinazioni per il Livello del Catalogo sono:

• Variante/Variante: Cattura le varianti con gli eventi utente e restituisce le varianti con le previsioni.
• Master/Master: Cattura gli articoli master con gli eventi utente e restituisce gli articoli master con le previsioni.
• Variante/Master: Cattura le varianti con gli eventi utente e restituisce gli articoli master con le previsioni.