Formato de Catálogo Heredado

Legacy format

Este es el formato de catálogo heredado, documentado aquí para referencia. Las nuevas integraciones deben usar el formato actual, que es más expresivo y cuenta con mejor soporte.

---

Definición

Un catálogo de productos representa toda la colección de productos disponibles para comprar 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

El ejemplo anterior incluye saltos de línea para facilitar la lectura. En un archivo de catálogo, cada producto debe ser una única línea codificada en JSON. 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 (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 identificador de producto "maestro". Esto enlaza todas las variantes de producto relacionadas para los resultados de predicción.

Todos los elementos del catálogo deben tener un valor para itemGroupId o ninguno de ellos puede tenerlo. No se pueden importar datos de catálogo con itemGroupId configurado para algunos elementos pero no para otros. Este campo es obligatorio cuando se utilizan los niveles de catálogo Maestro/Maestro o Variante/Maestro.

categoryHierarchies

• Tipo: Array
• Obligatorio (se requiere al menos una entrada)
• Tamaño máximo: 1.000 bytes (cuando se codifica como JSON)

Categorías de los elementos del catálogo. Este campo se repite para admitir que un producto pertenezca a varias jerarquías de categorías paralelas.

Por ejemplo, si un producto de calzado 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

El título del producto.

description

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

La descripción del producto. 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 y la descripción. Use las etiquetas de idioma definidas por BCP 47. Los 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

La disponibilidad del producto. Debe ser uno de:

• IN_STOCK — Artículo en stock.
• OUT_OF_STOCK — Artículo agotado.
• PREORDER — Artículo disponible para pre-ordenar.
• BACKORDER — Artículo temporalmente agotado pero disponible para pedido pendiente.

availableQuantity

• Tipo: Number
• Anidado bajo: productMetadata

La cantidad restante del artículo disponible para comprar.

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 cualquier descuento.

displayPrice

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

El precio actual del artículo después de cualquier descuento.

currencyCode

• Tipo: String
• Obligatorio

El código de moneda para todos los precios de los artículos. Use el código de tres caracteres ISO 4217 (por ejemplo, "USD", "AUD", "GBP").

canonicalProductUri

• Tipo: String
• Obligatorio

La URI base del producto. Si su producto tiene diferentes URIs para diferentes colores o tamaños, proporcione la URI para el producto base sin parámetros de variante siempre que sea posible.

images

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

Un array de imágenes del producto. Solo la primera imagen se muestra en los widgets 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: 1.000 bytes.
  "uri": "https://www.store.com/images/805371.jpg",
  // Opcional. Ancho de la imagen en píxeles.
  "width": 500,
  // Opcional. Alto de la imagen en píxeles.
  "height": 500
}

tags

• Tipo: Array de strings
• 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 combinada de todas las etiquetas para un solo elemento no debe exceder los 500 bytes.

itemAttributes

• Tipo: Object
• Tamaño máximo: 1.000 bytes (combinados)

Atributos adicionales opcionales 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 proporcionan señales adicionales para los modelos de recomendación.

Los atributos de los elementos 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 agregar datos personalizados a un producto para su uso con características específicas de Fanplayr.

Por ejemplo, para configurar palabras clave y muestras de color en Personal Shopper o Product Tag Explorers:

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

Formato del archivo de catálogo

El archivo de catálogo debe cumplir los siguientes requisitos:

• Cada elemento del catálogo debe estar formateado usando la estructura JSON descrita anteriormente.
• Cada elemento del catálogo debe estar contenido en una sola línea (formato JSONL).
• El tamaño total del archivo no debe exceder los 50 MB sin comprimir. Si su catálogo excede esto, divídalo e impórtelo en varios archivos.
• Todos los elementos deben usar el mismo idioma y moneda. No es posible mezclar idiomas o monedas dentro de un solo catálogo, ya que esto afectaría el entrenamiento del modelo de IA. Gestione catálogos separados si su tienda tiene múltiples vistas con diferentes idiomas 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 maestros o variantes con sus eventos de usuario en el sitio, y si desea devolver elementos maestros o variantes con las predicciones. Fanplayr le ayudará a configurar su integración.

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

Las posibles configuraciones de nivel de catálogo son:

• Variante/Variante — Captura variantes con eventos de usuario y devuelve variantes con predicciones.
• Maestro/Maestro — Captura elementos maestros con eventos de usuario y devuelve elementos maestros con predicciones.
• Variante/Maestro — Captura variantes con eventos de usuario y devuelve elementos maestros con predicciones.