Saltar al contenido principal

Introducción

Bloques de contenido reutilizables que se pueden usar en múltiples páginas.

Más información sobre la interfaz de usuario del módulo https://doc.oneentry.cloud/docs/category/blocks

🎯 ¿Qué hace este módulo?​

El módulo Blocks te permite obtener componentes de contenido reutilizables (bloques) — conjuntos de atributos que creas una vez en el panel de administración y reutilizas en páginas y páginas de productos: encabezados, pies de página, banners, testimonios, deslizadores y widgets de productos/recomendaciones. Actualiza un bloque una vez y se cambia en todas partes donde se utiliza.

El SDK es solo de lectura: obtienes bloques aquí y los creas o editas en el panel de administración de OneEntry.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


const { Blocks } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Obtén un solo bloque por su marcador y lee sus atributos:

// Fetch the "footer" block.
const block = await Blocks.getBlockByMarker("footer", "en_US");

console.log(block.identifier, block.type, block.isVisible);
// "footer" "common_block" true

// Custom fields live in attributeValues.
console.log(block.attributeValues);

✨ Conceptos Clave​

¿Qué es un Bloque?​

Un bloque es un componente de contenido reutilizable que contiene:

  • identifier — marcador único utilizado para referenciarlo en el código (siempre usa el marcador; nunca cambia)
  • localizeInfos — datos localizados (por ejemplo, title), contenido diferente por idioma
  • type — el BlockType que determina lo que renderiza el bloque
  • isVisible — bandera de visibilidad
  • attributeValues — campos personalizados que defines a través de AttributesSets

Estructura del Bloque​

{
  id: 3, // unique ID
  localizeInfos: { // block localized data
    title: 'Block', // block localized title
  },
  version: 0, // block version
  position: 1, // block position in array of blocks
  identifier: 'block', // block identifier (marker)
  type: 'common_block', // block type
  templateIdentifier: null, // template identifier
  isVisible: true, // visibility
  attributeValues: {}, // block attributes
}

📋 Lo Que Necesitas Saber​

  • Referencia bloques por marcador (identifier) en el código — los marcadores nunca cambian.
  • Los bloques se crean en el panel de administración. El SDK es de solo lectura.
  • Los campos personalizados provienen de AttributesSets. Ejemplos: un bloque de pie de página (derechos de autor, enlaces sociales, información de contacto), un banner principal (título, CTA, imagen de fondo), un testimonio (autor, foto, cita, calificación).
  • Bloques vs. Páginas. Una página es un documento autónomo con una URL (por ejemplo, /about) creado en el módulo de Páginas; un bloque es un componente reutilizable que insertas en páginas.
  • Los métodos de productos y recomendaciones devuelven un contenedor, no un array. getCartComplement, getCartSimilar, getWishlistSimilar, sus variantes …ByProductIds, getTrending, getPersonalRecommendations, getRecentlyViewed, getRepeatPurchase y getFrequentlyOrderedProducts se resuelven a un IProductsResponse - lee los productos de items, los conteos de total / totalFound.

📊 Tabla de Referencia Rápida - Métodos Comunes​

MétodoQué HaceCuándo Usar
getBlocks()Obtener todos los bloques (paginados, filtrados)Listar todos los bloques disponibles
getBlockByMarker()Obtener bloque por marcadorObtener bloque específico en el código
searchBlock()Buscar bloquesObtener bloques
getFrequentlyOrderedProducts()Productos frecuentemente ordenados"A menudo ordenados juntos"
getCartComplement()"Completa tu carrito" por contexto del carritoVenta cruzada desde el carrito
getCartComplementByProductIds()"Completa tu carrito" por productIdsVenta cruzada para productos dados
getCartSimilar()"Similar al carrito" por contexto del carritoAlternativas a los artículos del carrito
getCartSimilarByProductIds()"Similar al carrito" por productIdsAlternativas para productos dados
getWishlistSimilar()"Similar a la lista de deseos" por lista de deseosAlternativas a los artículos de la lista de deseos
getWishlistSimilarByProductIds()"Similar a la lista de deseos" por productIdsAlternativas para productos dados
getPersonalRecommendations()Recomendaciones personalesFeed de productos personalizados
getRecentlyViewed()Productos vistos recientementeWidget de "Vistos recientemente"
getRepeatPurchase()Productos para compra repetidaWidget de "Comprar de nuevo"
getTrending()Productos en tendenciaWidget de "Tendencias ahora"
getSlides()Árbol de diapositivas del bloque deslizanteRenderizar un deslizador/carrusel

🧩 Tipos de Bloques​

El type de un bloque (el BlockType) determina lo que renderiza. Además de los tipos base (common_block, product_block, similar_products_block, form, y otros), están disponibles los siguientes tipos de bloques de productos y personalización:

Tipo de bloqueMétodo
frequently_ordered_blockgetFrequentlyOrderedProducts()
trending_blockgetTrending()
recently_viewed_blockgetRecentlyViewed()
repeat_purchase_blockgetRepeatPurchase()
slider_blockgetSlides()
personal_recommendations_blockgetPersonalRecommendations()
cart_complement_blockgetCartComplement() / getCartComplementByProductIds()
cart_similar_blockgetCartSimilar() / getCartSimilarByProductIds()
wishlist_similar_blockgetWishlistSimilar() / getWishlistSimilarByProductIds()

Los bloques de personalización (vistos recientemente, compra repetida, recomendaciones personales, carrito/lista de deseos) se basan en la actividad del usuario rastreada y funcionan tanto para usuarios autorizados como para invitados (ver Modo invitado).

Fijando el precio (signPrice)​

Los métodos de bloques de productos y recomendaciones (getCartSimilar, getRecentlyViewed, getTrending, getPersonalRecommendations, getRepeatPurchase, getCartComplement, getFrequentlyOrderedProducts, …) aceptan un argumento opcional signPrice. Toma el marcador de un almacenamiento de pedidos y le pide al servidor que bloquee los precios de los productos devueltos por un tiempo limitado, de modo que el precio que un cliente ve en un widget de recomendación es el precio que paga al finalizar la compra.

signPrice — tipo string

Marcador de almacenamiento de pedidos para fijar precios. Si se establece el parámetro, el precio se fija por un cierto tiempo.

  • En los métodos de recomendación, signPrice es el último argumento posicional (después de langCode).
  • En las variantes …ByProductIds (getCartSimilarByProductIds, getCartComplementByProductIds, …) es un campo del body de la solicitud (body.signPrice).

Cada producto devuelto lleva un token signedPrice que codifica el precio bloqueado:


const products = await Blocks.getCartSimilar("cart_similar_block", "en_US", "orders");

const signedPrice = products[0].signedPrice;

➡️ Reutiliza ese token al crear el pedido — consulta la sección Precio de producto fijo (signedPrice) del módulo de Pedidos. El mismo parámetro de fijación de precios también existe en el módulo de Productos (en userQuery.signPrice).

Limitando el número de productos (limit)​

Ocho métodos de recomendación — getFrequentlyOrderedProducts, getCartComplement, getCartSimilar, getWishlistSimilar, getPersonalRecommendations, getRecentlyViewed, getRepeatPurchase y getTrending — aceptan un limit opcional como su último argumento posicional, después de signPrice.

limit — tipo number

Número máximo de productos a devolver. No tiene valor predeterminado por el SDK: cuando lo omites, se aplica la configuración de cantidad del bloque desde el panel de administración, por lo que las llamadas existentes se comportan exactamente como antes.

// The block's own quantity setting decides how many products come back.
const widget = await Blocks.getTrending('trending_block');

// Ask for at most 4 - e.g. a compact carousel on mobile.
const compact = await Blocks.getTrending('trending_block', 'en_US', undefined, 4);

En las variantes …ByProductIds (getCartComplementByProductIds, getCartSimilarByProductIds, getWishlistSimilarByProductIds) es un campo del body de la solicitud en su lugar (body.limit), junto con productIds, langCode y signPrice.

❓ Preguntas Comunes (FAQ)​

¿Cuál es la diferencia entre Bloques y Páginas?​

  • Páginas/Páginas de Productos — páginas autónomas con URLs (por ejemplo, /about) creadas en el módulo de Páginas, a las que agregas bloques y otros componentes.
  • Bloques — componentes reutilizables insertados en páginas (por ejemplo, un pie de página).

Piensa en una página como un documento completo y un bloque como un párrafo que reutilizas en documentos.

¿Cómo actualizo el contenido de un bloque?​

Edítalo en el panel de administración de OneEntry (sección de Bloques). Todas las páginas que utilizan ese bloque se actualizan automáticamente.

¿Debería crear muchos bloques pequeños o pocos bloques grandes?​

Prefiere muchos bloques pequeños y enfocados (por ejemplo, header_logo, footer_social_links) en lugar de un gran bloque entire_page_layout — los bloques pequeños son más fáciles de reutilizar y mantener.

¿Cómo muestro/oculto bloques condicionalmente?​

Verifica el campo isVisible en el bloque obtenido.

¿Cómo manejo la falta de bloques de manera elegante?​

Envuelve la obtención en un try/catch y renderiza un fallback cuando no se encuentra un bloque.

🎓 Mejores Prácticas​

  • Crea bloques pequeños y enfocados (responsabilidad única).
  • Usa marcadores descriptivos (global_footer, no block1); en minúsculas con guiones bajos.
  • Referencia bloques por marcador en el código — los marcadores nunca cambian.
  • Almacena en caché los bloques — cambian raramente.
  • Maneja la falta de bloques de manera elegante (try/catch).

🔗 Documentación Relacionada​