Formato Catalogo Legacy

Formato legacy

Questo è il formato catalogo legacy, documentato qui per riferimento. Le nuove integrazioni dovrebbero usare il formato attuale, che è più espressivo e meglio supportato.

---

Definizione

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

Ogni articolo 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
      }
    ]
  }
}

L'esempio sopra include interruzioni di riga per leggibilità. In un file di catalogo, ogni prodotto deve essere una singola riga codificata JSON. 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 articoli 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 di catalogo)
• Dimensione massima: 128 byte

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

Tutti gli articoli del catalogo devono avere un valore per itemGroupId oppure nessuno di essi. Non è possibile importare dati di catalogo con itemGroupId impostato per alcuni articoli ma non per altri. Questo campo è obbligatorio quando si utilizzano i livelli di catalogo Master/Master o Variant/Master.

categoryHierarchies

• Tipo: Array
• Obbligatorio (è richiesto almeno un elemento)
• Dimensione massima: 1.000 byte (quando codificato come JSON)

Categorie dell'articolo del catalogo. Questo campo è ripetuto per supportare un prodotto che appartiene a diverse gerarchie di categorie parallele.

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

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

title

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

Il titolo del prodotto.

description

• Tipo: Stringa
• Dimensione massima: 500 byte

La descrizione del prodotto. Può aiutare a migliorare il modello di raccomandazione.

brand

• Tipo: Stringa
• Dimensione massima: 100 byte

Il marchio o produttore associato al prodotto.

languageCode

• Tipo: Stringa
• Obbligatorio

La lingua del titolo e della descrizione. Utilizzare i tag di lingua definiti da BCP 47. I 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
• Nidificato sotto: productMetadata
• Obbligatorio

La disponibilità del prodotto. Deve essere uno dei seguenti:

• IN_STOCK — Articolo in magazzino.
• OUT_OF_STOCK — Articolo esaurito.
• PREORDER — Articolo disponibile per il pre-ordine.
• BACKORDER — Articolo temporaneamente esaurito ma disponibile per l'ordine in arretrato.

availableQuantity

• Tipo: Numero
• Nidificato sotto: productMetadata

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

exactPrice

• Tipo: Oggetto
• Obbligatorio

Contiene le proprietà originalPrice e displayPrice.

originalPrice

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

Il prezzo originale dell'articolo prima di eventuali sconti.

displayPrice

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

Il prezzo attuale dell'articolo dopo eventuali sconti.

currencyCode

• Tipo: Stringa
• Obbligatorio

Il codice valuta per tutti i prezzi degli articoli. Utilizzare il codice ISO 4217 a tre caratteri (ad es. "USD", "AUD", "GBP").

canonicalProductUri

• Tipo: Stringa
• Obbligatorio

L'URI base del prodotto. Se il tuo prodotto ha URI diversi per colori o dimensioni diverse, fornisci l'URI per il prodotto base senza parametri di variante, ove possibile.

images

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

Un array di immagini del prodotto. Solo la prima immagine viene visualizzata nei widget di raccomandazione. È richiesta almeno un'immagine.

Ogni immagine dovrebbe essere un oggetto con la seguente struttura:

{
  // Obbligatorio. URL dell'immagine. Dimensione massima: 1.000 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 stringhe
• Dimensione massima: 500 byte (combinati)

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

itemAttributes

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

Attributi extra opzionali 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 forniscono segnali aggiuntivi per i modelli di raccomandazione.

Gli attributi dell'articolo dovrebbero essere divisi in insiemi 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]
    }
  }
}

customData

Dati personalizzati possono essere aggiunti a un prodotto per l'uso con specifiche funzionalità Fanplayr.

Ad esempio, per impostare parole chiave e campioni di colore in Personal Shopper o Product Tag Explorers:

"customData": {
  "keywords": [
    { "text": "ON SALE", "bg": "#ff0000", "fg": "#fff" },
    { "text": "Special Brand" }
  ],
  "colors": ["red", "#00ff00"]
}

Formato del file di catalogo

Il file di catalogo deve soddisfare i seguenti requisiti:

• Ogni articolo del catalogo deve essere formattato utilizzando la struttura JSON descritta sopra.
• Ogni articolo del catalogo deve essere contenuto su una singola riga (formato JSONL).
• La dimensione totale del file non deve superare i 50 MB non compressi. Se il tuo catalogo supera questa dimensione, dividilo e importalo in più file.
• Tutti gli articoli devono utilizzare la stessa lingua e valuta. Non è possibile mescolare lingue o valute all'interno di un singolo catalogo, poiché ciò influirebbe sull'addestramento del modello AI. Gestisci cataloghi separati se il tuo negozio ha più visualizzazioni con lingue 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 di catalogo

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

Gli articoli master rappresentano un gruppo di articoli simili (un gruppo SKU). Ad esempio, un 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 configurazioni del livello di catalogo sono:

• Variante/Variante — Acquisisci varianti con eventi utente e restituisci varianti con previsioni.
• Master/Master — Acquisisci articoli master con eventi utente e restituisci articoli master con previsioni.
• Variante/Master — Acquisisci varianti con eventi utente e restituisci articoli master con previsioni.