Riferimento ai campi

Questa pagina documenta tutti i campi supportati nel Catalogo Prodotti Fanplayr. Usala per comprendere quali dati di prodotto Fanplayr può elaborare e come ogni campo dovrebbe essere strutturato.

Non sai da dove iniziare?

Se non hai familiarità con il formato del catalogo, leggi prima la Panoramica. Spiega concetti chiave come il modello di prodotto PRIMARY/VARIANT e quali campi sono più importanti.

Prodotto

L'oggetto Product è la struttura di più alto livello per ogni articolo nel catalogo. L'interfaccia TypeScript qui sotto offre agli sviluppatori una rapida panoramica della forma completa — passa il mouse su qualsiasi tipo per esplorarlo. I lettori non tecnici possono passare direttamente alle descrizioni dei campi qui sotto.

interface Product {
  id: string; // required
  type?: Type;
  primaryProductId?: string;
  categories: string[]; // required
  title: string; // required
  brands?: string[];
  description?: string;
  languageCode?: string;
  priceInfo: PriceInfo; // required
  availability?: Availability;
  availableQuantity?: number;
  uri: string; // required
  images?: Image[];
  audience?: Audience;
  colorInfo?: ColorInfo;
  sizes?: string[];
  materials?: string[];
  patterns?: string[];
  conditions?: string[];
}

Esempio

Un esempio completo di un oggetto Product valido:

{
  "id": "805371A",
  "type": "PRIMARY",
  "categories": ["Women > Shoes", "Sports & Fitness > Shoes"],
  "title": "Red Shoes",
  "description": "Fancy red shoes",
  "brands": ["Designer Brand"],
  "availability": "IN_STOCK",
  "availableQuantity": 30,
  "languageCode": "en",
  "priceInfo": {
    "price": 89.99,
    "originalPrice": 119.99,
    "currencyCode": "USD"
  },
  "uri": "https://www.store.com/shoes/red-shoes",
  "images": [
    {
      "uri": "https://www.store.com/images/805371.jpg",
      "width": 500,
      "height": 500
    }
  ]
}

INFO

L'esempio sopra include interruzioni di riga per leggibilità. In un file di catalogo, ogni prodotto deve essere una singola riga codificata in JSON. Il file deve essere codificato in UTF-8.

Campi

id

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

Un identificatore unico per questo prodotto all'interno del catalogo. Nessun due prodotti nello stesso catalogo possono condividere lo stesso id.

Questo valore deve corrispondere all'ID del prodotto tracciato nella tua integrazione Fanplayr — è utilizzato per correlare i dati del catalogo con il comportamento degli acquirenti, come le visualizzazioni delle pagine prodotto e gli acquisti.

type

• Tipo: enum Type
• Predefinito: dedotto da primaryProductId

Indica se questo prodotto è un prodotto di livello superiore (PRIMARY) o una sua variante (VARIANT). Vedi Type per l'elenco completo dei valori.

Nella maggior parte dei casi, questo campo può essere omesso — Fanplayr inferirà il valore corretto in base a primaryProductId:

• Predefinito su 'PRIMARY' quando primaryProductId è assente o uguale a id.
• Predefinito su 'VARIANT' quando primaryProductId differisce da id.

primaryProductId

• Tipo: string

L'id del prodotto PRIMARY a cui appartiene questa variante. Utilizzato per raggruppare le varianti sotto il loro prodotto padre.

• Per i prodotti PRIMARY: lasciare vuoto, o impostare lo stesso valore di id.
• Per i prodotti VARIANT: deve essere impostato sull'id del prodotto padre PRIMARY.

categories

• Tipo: string[]
• Obbligatorio (almeno un elemento)
• Dimensione massima: 1.000 byte (codificato come JSON)

Le categorie a cui appartiene questo prodotto. Un prodotto può appartenere a più categorie. Fornire il percorso completo della categoria — piuttosto che solo la categoria foglia — migliora significativamente la qualità delle raccomandazioni e della ricerca.

Usa > per separare i livelli della gerarchia. Se > appare in un nome di categoria, sostituiscilo con un altro carattere come "|".

"categories": [
  "Shoes & Accessories > Shoes",
  "Sports & Fitness > Athletic Clothing > Shoes"
]

title

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

Il nome del prodotto come appare sul tuo storefront. Questo valore viene visualizzato nei widget di raccomandazione mostrati agli acquirenti, quindi dovrebbe corrispondere esattamente al tuo storefront.

brands

• Tipo: string[]
• Dimensione massima: 1.000 byte (codificato come JSON)

Il marchio associato a questo prodotto. Utilizzato per alimentare il filtro e le raccomandazioni basate sul marchio. Sono supportati più marchi, se necessario.

description

• Tipo: string
• Dimensione massima: 500 byte

Una descrizione testuale del prodotto. Utilizzata per migliorare la rilevanza delle raccomandazioni. Fornire una buona descrizione aiuta Fanplayr a comprendere meglio cos'è il prodotto.

languageCode

• Tipo: string

La lingua utilizzata nei campi di testo come title e description. Deve essere un tag lingua BCP 47 valido (ad es. "en", "fr", "de").

priceInfo

• Tipo: oggetto PriceInfo
• Obbligatorio

Informazioni sui prezzi per questo prodotto, inclusi prezzo attuale, prezzo originale e valuta. Vedi PriceInfo per tutti i dettagli.

availability

• Tipo: enum Availability
• Predefinito: 'IN_STOCK'

La disponibilità attuale del prodotto. Fanplayr utilizza questo campo per evitare di raccomandare prodotti che gli acquirenti non possono acquistare. Vedi Availability per l'elenco completo dei valori.

availableQuantity

• Tipo: number

Il numero di unità attualmente in magazzino.

uri

• Tipo: string
• Obbligatorio

L'URL canonico della pagina dei dettagli del prodotto. Utilizzato come destinazione del link quando un prodotto viene mostrato in un widget di raccomandazione.

images

• Tipo: oggetto[] Image

Un elenco di immagini per questo prodotto. Le immagini del prodotto vengono visualizzate direttamente nei widget di raccomandazione — è fortemente consigliato fornire immagini accurate e di alta qualità. Le immagini dovrebbero essere di almeno 500×500px. Vedi Image per tutti i dettagli.

audience

• Tipo: oggetto Audience

Il pubblico di destinazione per questo prodotto. Fornire dati sul pubblico aiuta Fanplayr a offrire raccomandazioni più pertinenti — ad esempio, evitando di raccomandare prodotti da uomo su una pagina di categoria femminile. Vedi Audience per tutti i dettagli.

colorInfo

• Tipo: oggetto ColorInfo

Informazioni sul colore del prodotto. Particolarmente preziose per i negozi di moda e abbigliamento. Fornire questo campo abilita il filtraggio basato sul colore, migliora le raccomandazioni e permette la visualizzazione di campioni di colore nei widget di raccomandazione dei prodotti. Vedi ColorInfo per tutti i dettagli.

sizes

• Tipo: string[]
• Massimo: 20 valori

Le taglie disponibili per questo prodotto. Per rappresentare diversi sistemi di taglie o tipi di taglie, usa il formato [[size_system:]size_type:]size_value]:

• "US:MENS:M" — sistema di taglie US, tipo di taglia MENS, valore della taglia M
• "GIRLS:27" — nessun sistema di taglie, tipo di taglia GIRLS, valore della taglia 27
• "32 inches" — nessun sistema o tipo di taglia, valore della taglia 32 inches

materials

• Tipo: string[]
• Massimo: 20 valori

Il materiale o i materiali di cui è fatto questo prodotto (ad es. "leather", "cotton", "wood").

patterns

• Tipo: string[]
• Massimo: 20 valori

La fantasia o la stampa grafica del prodotto (ad es. "striped", "polka dot", "paisley").

conditions

• Tipo: string[]
• Massimo: 1 valore

La condizione del prodotto. Sebbene sia definito come un array per coerenza con altri campi, è supportato un solo valore. Usa i valori standard dove possibile:

• "new"
• "refurbished"
• "used"

---

Tipi

I seguenti tipi sono referenziati dai campi nell'oggetto Product.

Type

Il tipo di un prodotto. Determina se questo prodotto è un articolo di livello superiore o una variante di un altro.

Value	Description
"PRIMARY"	Un prodotto di livello superiore. I prodotti PRIMARY possono avere più prodotti VARIANT raggruppati sotto di essi.
"VARIANT"	Una variazione di un prodotto PRIMARY. Le varianti tipicamente condividono attributi come il title e il brand con il loro genitore, ma differiscono in proprietà come size, colour o price.

PriceInfo

Informazioni sui prezzi per un prodotto.

interface PriceInfo {
  currencyCode: string; // required
  price: number; // required
  originalPrice?: number;
  cost?: number;
}

currencyCode

• Tipo: string
• Obbligatorio

Il codice valuta ISO 4217 di 3 lettere per tutti i prezzi in questo oggetto (ad es. "USD", "AUD", "GBP").

price

• Tipo: number
• Obbligatorio

Il prezzo di vendita attuale del prodotto. Questo è il prezzo mostrato agli acquirenti e utilizzato nei widget di raccomandazione.

originalPrice

• Tipo: number

Il prezzo del prodotto prima di qualsiasi sconto. Se omesso o zero, il valore predefinito è quello di price. Se fornito, originalPrice deve essere maggiore o uguale a price. Fornire questo campo consente a Fanplayr di identificare e targettizzare prodotti in saldo e scontati.

cost

• Tipo: number

Il costo delle merci per questo prodotto. Utilizzato internamente per la reportistica sul profitto lordo. Questo valore non viene mai mostrato agli acquirenti.

Availability

Lo stato di disponibilità di un prodotto. Fanplayr lo utilizza per evitare di raccomandare prodotti che gli acquirenti non possono acquistare.

• Predefinito: "IN_STOCK"

Value	Description
"IN_STOCK"	Il prodotto è disponibile per l'acquisto immediato.
"OUT_OF_STOCK"	Il prodotto non è attualmente disponibile.
"PREORDER"	Il prodotto non è ancora stato rilasciato ma è disponibile per il preordine.
"BACKORDER"	Il prodotto è temporaneamente esaurito ma disponibile per l'ordine in arretrato.

Image

Un'immagine associata a un prodotto. Le immagini vengono visualizzate direttamente nei widget di raccomandazione. Le immagini dovrebbero essere di almeno 500×500px.

interface Image {
  uri: string; // required
  width?: number;
  height?: number;
}

uri

• Tipo: string
• Obbligatorio

L'URL dell'immagine. Deve essere un URI valido codificato UTF-8 con una lunghezza massima di 5.000 caratteri.

width

• Tipo: number

La larghezza dell'immagine in pixel.

height

• Tipo: number

L'altezza dell'immagine in pixel.

Audience

Il pubblico di destinazione per un prodotto, utilizzato per migliorare la rilevanza delle raccomandazioni.

interface Audience {
  genders?: Gender[];
  ageGroups?: AgeGroup[];
}

genders

• Tipo: ('male' | 'female' | 'unisex')[]
• Massimo: 5 valori

I generi a cui è destinato questo prodotto. Usa i valori standard dove possibile:

• "male"
• "female"
• "unisex"

ageGroups

• Tipo: ('newborn' | 'infant' | 'toddler' | 'kids' | 'adult')[]
• Massimo: 5 valori

I gruppi di età a cui è destinato questo prodotto. Usa i valori standard dove possibile:

• "newborn" — fino a 3 mesi di età
• "infant" — da 3 a 12 mesi di età
• "toddler" — da 1 a 5 anni di età
• "kids" — da 5 a 13 anni di età
• "adult" — tipicamente adolescenti o più grandi

ColorInfo

Informazioni sul colore per un prodotto. Particolarmente preziose per i negozi di moda e abbigliamento. Fornire questo campo abilita il filtraggio basato sul colore, migliora le raccomandazioni e consente la visualizzazione di campioni di colore nei widget di raccomandazione dei prodotti.

interface ColorInfo {
  colorFamilies?: string[];
  colors?: string[];
}

colorFamilies

• Tipo: string[]
• Massimo: 5 valori

L'ampia famiglia o le ampie famiglie di colori a cui appartiene questo prodotto. Normalmente un prodotto ha una sola famiglia di colori — usa "Mixed" anziché più valori quando appropriato.

Usa i valori standard dove possibile:

"Red" "Pink" "Orange" "Yellow" "Purple" "Green" "Cyan" "Blue" "Brown" "White" "Gray" "Black" "Mixed"

colors

• Tipo: string[]
• Massimo: 75 valori

Il nome o i nomi specifici del colore per questo prodotto, come appaiono sul tuo storefront (ad es. "Midnight Navy", "Rose Gold"). Questi possono differire dai valori standard di colorFamilies. Normalmente un prodotto ha un solo colore — usa "Mixed" anziché più valori quando appropriato.