Formato y requisitos del catálogo

Definición

Un catálogo de productos representa la colección completa de productos disponibles para su compra en una tienda de comercio electrónico.

Cada elemento del catálogo se representa como un objeto JSON con la siguiente estructura:

{
  "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
      }
    ]
  }
}

INFO

Nota: El ejemplo anterior incluye saltos de línea para facilitar la lectura; sin embargo, el archivo de catálogo que cree debe incluir un elemento de catálogo codificado en JSON por línea. El archivo también debe estar codificado en 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}]}}

Propiedades

id

• Tipo: String
• Obligatorio
• Tamaño máximo: 128 bytes

Este ID debe ser único entre todos los elementos del catálogo dentro del mismo catálogo. Debe ser el mismo ID que se rastrea con las vistas de página de producto en su integración de Fanplayr.

itemGroupId

• Tipo: String
• Obligatorio (según la configuración del nivel de catálogo)
• Tamaño máximo: 128 bytes

Identificador de grupo de variante de producto, también conocido como identificador de producto "maestro". Esto vincula todas las variantes de producto relacionadas para los resultados de predicción.

Todos sus elementos de catálogo deben tener un valor para itemGroupId o ninguno de ellos puede tenerlo. No puede importar datos de catálogo con itemGroupId establecido para algunos elementos pero no para otros. Este campo es obligatorio cuando se utiliza el nivel de catálogo Maestro/Maestro o Variante/Maestro.

categoryHierarchies

• Tipo: Array
• Obligatorio (se requiere al menos una entrada de jerarquía de categorías)
• Tamaño máximo: 1000 bytes (cuando se codifica como JSON)

Categorías de elementos del catálogo. Este campo se repite para admitir que un elemento del catálogo pertenezca a varias jerarquías de categorías paralelas. Debe estar presente al menos una categoría.

Por ejemplo, si un producto de zapatos pertenece tanto a Mujer > Zapatos como a Deportes y Fitness > Zapatos, podría representarse como:

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

title

• Tipo: String
• Obligatorio
• Tamaño máximo: 500 bytes

Título del elemento del catálogo.

description

• Tipo: String
• Tamaño máximo: 500 bytes

Descripción del elemento del catálogo. Este valor no se puede mostrar en los widgets, pero puede ayudar a mejorar el modelo de recomendación.

brand

• Tipo: String
• Tamaño máximo: 100 bytes

La marca o fabricante asociado con el producto.

languageCode

• Tipo: String
• Obligatorio

El idioma del título/descripción. Use etiquetas de idioma definidas por BCP 47. https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Nuestros códigos de idioma admitidos incluyen "en", "es", "fr", "de", "ar", "fa", "zh", "ja", "ko", "sv", "ro", "nl".

productMetadata

• Tipo: Object
• Obligatorio

Contiene las propiedades stockState, availableQuantity, exactPrice, currencyCode, canonicalProductUri e images.

stockState

• Tipo: ENUM
• Anidado en: productMetadata
• Obligatorio

Debe ser igual a uno de los siguientes valores:

• IN_STOCK - Artículo en stock.
• OUT_OF_STOCK - Artículo agotado.
• PREORDER - Artículo en estado de pre-pedido.
• BACKORDER - Artículo en espera (es decir, temporalmente agotado).

availableQuantity

• Tipo: Number
• Anidado en: productMetadata

La cantidad restante del artículo disponible para la compra.

exactPrice

• Tipo: Object
• Obligatorio:

Contiene las propiedades originalPrice y displayPrice.

originalPrice

• Tipo: Float
• Anidado en: productMetadata.exactPrice
• Obligatorio

El precio original del artículo antes de descuentos como los precios de venta.

displayPrice

• Tipo: Float
• Anidado en: productMetadata.exactPrice
• Obligatorio

El precio actual del artículo después de descuentos como los precios de venta.

currencyCode

• Tipo: String
• Obligatorio

El código de moneda para los precios del artículo. Utilice el código ISO-4217 de tres caracteres.

canonicalProductUri

• Tipo: String
• Obligatorio

La URI base del producto. Si su producto tiene diferentes URIs para diferentes colores o tamaños, si es posible, proporcione la URI que apunta al producto base sin variantes.

images

• Tipo: Array
• Obligatorio (se requiere al menos una imagen)

Un array de imágenes del producto. Solo la primera imagen se muestra en el componente de Recomendación. Se requiere al menos una imagen.

Cada imagen debe ser un objeto con la siguiente estructura:

{
  // Obligatorio. URL de la imagen.
  // Tamaño máximo: 1000 bytes
  "uri": "https://www.store.com/images/805371.jpg",
  // Opcional. Ancho de la imagen en píxeles.
  "width": 500,
  // Opcional. Altura de la imagen en píxeles.
  "height": 500
}

tags

• Tipo: Array de String
• Tamaño máximo: 500 bytes (combinado)

Etiquetas opcionales para asociar con el elemento del catálogo. Cada una debe ser una cadena codificada en UTF-8. La longitud total de todas las etiquetas para un solo elemento del catálogo no debe exceder los 500 bytes.

itemAttributes

• Tipo: Object
• Tamaño máximo: 1000 bytes (combinado)

Opcional. Atributos adicionales del artículo para incluir en el modelo de recomendación. Por ejemplo, para productos minoristas, esto podría incluir el estilo del producto, el color, etc. Estos atributos pueden añadir señales adicionales para los modelos de recomendación.

Los atributos del artículo deben dividirse en conjuntos categóricos y numéricos con la siguiente estructura:

"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

Se pueden añadir datos personalizados a un producto y utilizarlos para funcionalidades adicionales.

Por ejemplo, para establecer palabras clave y fichas de color en Personal Shopper o Product Tag Explorers, puede añadir lo siguiente:

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

Formato del archivo de catálogo

El formato del archivo de catálogo de productos tiene los siguientes requisitos:

• Cada elemento del catálogo debe estar formateado utilizando la estructura JSON descrita anteriormente.
• Cada elemento del catálogo debe contenerse en una sola línea.
• El tamaño total del archivo de catálogo no debe exceder los 50 MB sin comprimir. Si su catálogo excede este tamaño, puede dividirlo e importarlo varias veces.
• Todos los elementos deben usar el mismo idioma y moneda. No es posible mezclar diferentes idiomas y monedas en el mismo catálogo debido a limitaciones al entrenar modelos de IA. Deberá gestionar catálogos y proyectos separados si su tienda de comercio electrónico contiene múltiples vistas de tienda con diferentes idiomas y/o monedas.

El siguiente es un ejemplo de un archivo de catálogo con 2 elementos:

{"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}]}}

Niveles del catálogo

Antes de importar su catálogo por primera vez, debe determinar si desea rastrear elementos maestros o variantes con sus eventos de usuario en el sitio, y si desea que se devuelvan elementos maestros o variantes con sus predicciones. Fanplayr le ayudará a configurar su integración.

Los elementos maestros representan un grupo de elementos similares (en otras palabras, un grupo de SKU). Un ejemplo de un elemento maestro podría ser "Camisa de cuello en V", con variantes como "Camisa de cuello en V marrón, talla XL" y "Camisa de cuello en V blanca, talla S". Los maestros y las variantes a veces se describen como elementos "padre" e "hijo".

Las posibles combinaciones para el Nivel de Catálogo son:

• Variante/Variante: Capturar variantes con eventos de usuario y devolver variantes con predicciones.
• Maestro/Maestro: Capturar elementos maestros con eventos de usuario y devolver elementos maestros con predicciones.
• Variante/Maestro: Capturar variantes con eventos de usuario y devolver elementos maestros con predicciones.