Formato y requisitos del catálogo

Definición

Un catálogo de productos representa toda la colección de productos que están 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 visitas a páginas de productos en su integración de Fanplayr.

itemGroupId

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

Identificador de grupo de variantes de producto, también conocido como el 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 configurado para algunos elementos pero no para otros. Este campo es obligatorio cuando se utiliza el nivel de catálogo Master/Master o Variant/Master.

categoryHierarchies

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

Categorías del elemento del catálogo. Este campo se repite para permitir 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 así:

"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 el fabricante asociado al producto.

languageCode

• Tipo: String
• Obligatorio

El idioma del título/descripción. Utilice las 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 bajo: 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 reserva.
• BACKORDER - Artículo en pedido pendiente (es decir, temporalmente fuera de stock).

availableQuantity

• Tipo: Number
• Anidado bajo: 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 bajo: productMetadata.exactPrice
• Obligatorio

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

displayPrice

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

El precio actual del artículo después de descuentos como 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 de 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 of String
• Tamaño máximo: 500 bytes (combinados)

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 (combinados)

Opcional. Atributos adicionales del artículo que se incluirán en el modelo de recomendación. Por ejemplo, para productos minoristas, esto podría incluir el estilo, color, etc. del producto. 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]
    }
  }
}

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 estar contenido 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 de catálogo

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

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

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

• Variant/Variant: Captura variants con eventos de usuario y devuelve variants con predicciones.
• Master/Master: Captura elementos master con eventos de usuario y devuelve elementos master con predicciones.
• Variant/Master: Captura variants con eventos de usuario y devuelve elementos master con predicciones.