Preguntas frecuentes

Ocultar deslizador de categoría #

Cuando se añade una Recomendación de Clerk.io a una página de categoría que contiene pocos productos, mostrará los mismos productos en la página.

Para evitar esto, puedes ocultar la Recomendación en las páginas de categoría, añadiendo una declaración if al código de diseño de la Recomendación.

Cambia el número en la declaración if por la cantidad mínima de productos necesaria para mostrar la Recomendación.

{% if products.length > 7 %}
 
 <!-- Código de Recomendación -->

{% endif %}

Ejemplo:

{% if products.length > 7 %}
<div class="clerk-wrapper">
    <div class="clerk-headline-wrapper">
        <h2 class="clerk-headline">{{headline}}</h2>
    </div>
    <div class="clerk-slider-wrapper">
        <div class="clerk-slider">
            {% for item in products %}
            <div class="clerk-slider-content">
                <!-- INICIO TARJETA DE PRODUCTO -->
                <!-- FIN TARJETA DE PRODUCTO -->
            </div>
            {% endfor %}
        </div>
    </div>
</div>
{% endif %}

Este método solo oculta el deslizador, pero igual cuenta para tu uso de Recomendaciones. Para unas pocas categorías, este método funciona bien.

Sin embargo, si tienes muchas categorías con pocos productos, recomendamos bloquear la inyección del deslizador a nivel de servidor en su lugar.

Recomendar productos compatibles #

La IA de Clerk recomienda productos basándose en lo que es más probable que se compre junto. Esto funciona bien para la mayoría de las tiendas, pero algunos catálogos contienen productos que deben ser física o técnicamente compatibles, como repuestos de automóviles, componentes electrónicos o piezas de máquinas.

En estos casos, que un producto sea popular no basta. También debe ser compatible con el producto que el cliente está viendo.

La solución es etiquetar tus productos con atributos que definan la compatibilidad y luego usar el filtrado dinámico para limitar las recomendaciones solo a los productos compatibles.

La IA de Clerk seguirá determinando cuáles son los mejores productos para mostrar, pero solo dentro del subconjunto que pasa el filtro. Esto significa que obtienes lo mejor de ambos mundos: ordenación inteligente dentro de una selección compatible.

Añadir atributos #

Los atributos que necesitas dependen de cómo funciona la compatibilidad en tu catálogo. Deben sincronizarse con Clerk como parte de tus datos de producto, ya sea mediante tu integración o a través de la API.

Puedes verificar que tus atributos estén disponibles yendo a Data > Products y revisando cualquier producto.

Aquí hay tres patrones comunes, desde el más sencillo hasta el más avanzado.

Atributo único #

Si todos los productos del mismo proveedor son compatibles entre sí, añade el proveedor como un atributo en cada producto. Luego, filtra las recomendaciones para mostrar solo productos con ese mismo proveedor.

En tu código de embed, define una variable que contenga el proveedor del producto actual y úsalo como filtro:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter="vendor = $product_vendor">
</span>

var product_vendor = "ACME Corp";

Esto asegura que un cliente viendo un producto de ACME Corp solo verá recomendaciones de ese mismo proveedor.

Múltiples atributos #

A veces, un solo atributo no es suficiente. Por ejemplo, una pieza de auto podría necesitar coincidir tanto en la marca como en el modelo del vehículo.

Puedes combinar varias condiciones en un solo filtro:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter="make = $product_make and model = $product_model">
</span>

var product_make = "Toyota";
var product_model = "Corolla";

Solo se mostrarán productos que coincidan en ambos: marca y modelo.

Grupos de compatibilidad #

En catálogos más complejos, cada producto tiene una lista única de otros productos con los que es compatible, y esto no puede capturarse solo con atributos compartidos.

La solución es calcular un identificador de grupo basado en el conjunto de IDs de productos compatibles, y guardarlo como atributo. Los productos que comparten exactamente el mismo conjunto de ítems compatibles tendrán el mismo identificador, lo que permite filtrar por él.

Por ejemplo, si los productos A, B y C son compatibles entre sí, puedes calcular un hash a partir de sus IDs ordenadas y guardarlo como atributo compatibility_group en cada uno. Luego, filtrar por él:

<span class="clerk"
      data-template="@product-page-alternatives"
      data-products='["CURRENT_PRODUCT_ID"]'
      data-filter='compatibility_group = $product_group'>
</span>

var product_group = "a1b2c3d4";

Este método funciona bien cuando las relaciones de compatibilidad provienen de una base de datos externa o un sistema PIM. El hash debe recalcularse cada vez que cambie la información de compatibilidad y sincronizarse a Clerk junto con el resto de tus datos de producto.

Consejo: Si un producto puede pertenecer a varios grupos de compatibilidad, guarda los identificadores como un atributo tipo lista y usa el operador in en vez de =. Lee más sobre sintaxis de filtros.

Elegir el enfoque adecuado #

Comienza con el método más sencillo que cubra tu caso. Siempre puedes añadir más atributos después si necesitas un control más preciso.

Para profundizar en todas las maneras de usar filtros en códigos de embed, consulta Filtrado dinámico.

Mostrar Recommendations en un sidecart dinámico #

Un sidecart es un drawer, minicart, superposición o cualquier otra interfaz de carrito que se abre y actualiza sin cargar una nueva página. Su HTML puede cambiar cuando un visitante añade un producto, elimina un producto o cambia una cantidad.

Las Recommendations en este tipo de carrito deben seguir el estado vivo del carrito. Una Inyección normal que se renderiza solo al cargar la página no es suficiente. La implementación debe coordinar el sidecart, los eventos del carrito, el Element de Clerk.io y el diseño de la recomendación.

Antes de comenzar #

Inspecciona el sidecart en vivo antes de crear el Element o escribir el script de diseño. Anota el contenedor del sidecart, el área de contenido, el selector y atributo del ID de producto, el indicador de carga, los eventos de actualización del carrito y si las actualizaciones reemplazan el cuerpo del sidecart o todo el contenedor.

No copies selectores, atributos o eventos de otra tienda. La estructura del sidecart varía entre themes y plugins. Usa los eventos de carrito existentes de la plataforma siempre que sean fiables; de lo contrario, usa el MutationObserver más pequeño y filtrado posible para detectar cambios en el carrito. Evita observar todo el body sin filtrar, ya que el propio marcado de Clerk.io puede disparar el observer nuevamente.

Crear el Element #

Crea un Element dedicado para el sidecart. Usa la API recommendations/complementary y la lógica Best Cross-Sell Products. Configúralo para leer los IDs de producto del carrito en vivo, excluir productos ya en el carrito y devolver unos cuatro a ocho productos.

La configuración preferida es pasar los IDs del carrito en la configuración del Element: establece la API en recommendations/complementary, el tipo de ID en products, la fuente de ID en el Element y el selector y atributo de ID a los valores encontrados en el sidecart.

Si el sidecart no contiene sus IDs de producto cuando Clerk.io inicializa el Element, establece los parámetros desde el propio script de diseño:

contentElement.setAttribute("data-api", "recommendations/complementary");
contentElement.setAttribute("data-products", ids.join(","));
contentElement.setAttribute("data-exclude", ids.join(","));
contentElement.setAttribute("data-limit", "8");

Clerk("content", "#" + contentElement.id, function (content) {
  content.param({
    api: "recommendations/complementary",
    products: ids,
    exclude: ids,
    limit: 8
  });
});

Observa que esta configuración vía script es un fallback. Debe ejecutarse sólo cuando los IDs del carrito estén disponibles, no únicamente al cargar la página.

Montar el Element #

Coloca el Element en una ubicación estable y mueve la raíz de Recommendations renderizada hacia el sidecart después de que Clerk.io la genere. Usa clases independientes tipo clerk- para que el diseño no herede estilos de otros proveedores como hr- o aw-.

En escritorio, un carril de recomendaciones puede situarse junto al sidecart:

.clerk-sidecart-recs {
  position: absolute;
  top: 0;
  right: 100%;
  width: 250px;
  height: 100vh;
}

Si la plataforma recorta el carril, añade overflow: visible !important a la clase host del sidecart. En móvil, mueve la raíz dentro del cuerpo del sidecart y usa position: static.

Mantener las Recommendations actualizadas #

Las acciones del carrito suelen disparar varios eventos rápidamente y pueden reemplazar el cuerpo del sidecart. Debouncea los eventos del carrito y las mutaciones relevantes del DOM, y espera hasta que el carrito termine de actualizarse antes de renderizar.

Lleva un control de una key fabricada con los IDs actuales de los productos, por ejemplo ids.join(","). Renderiza solo cuando cambie la key final. Si los cambios de cantidad deben afectar las recomendaciones, incluye las cantidades en la key; de lo contrario, un cambio solo en cantidad no necesita una nueva petición de Recommendation.

Utiliza un render lock y un pequeño cooldown por key para evitar renders solapados o repetidos mientras los fragmentos se estabilizan. Si la raíz de Recommendation se elimina durante una actualización, recupérala una vez para la misma clave de carrito.

Sigue la clave del carrito en el Element y en la raíz visible de Recommendation. Antes de aplicar una respuesta asincrónica, compara la clave de la respuesta con la clave actual del carrito. Esto previene que una respuesta anterior reemplace las recomendaciones del carrito más reciente.

var key = ids.join(",");
contentElement.setAttribute("data-products", ids.join(","));
contentElement.setAttribute("data-exclude", ids.join(","));
contentElement.setAttribute("data-clerk-sidecart-request-key", key);
root.setAttribute("data-clerk-sidecart-render-key", key);

if (getCartProductIds().join(",") !== key) return;

Evita usar la presencia de tarjetas de producto existentes como único control. Un render inicial puede ocurrir antes de que los IDs de carrito estén disponibles y congelar el sidecart en productos incorrectos.

Render de respaldo (Fallback rendering) #

Si la raíz de Clerk.io desaparece tras una actualización del carrito, marca una raíz de respaldo creada manualmente con data-clerk-sidecart-fallback="true". Ocúltala mientras esté vacía o cargando, elimínala cuando aparezca una raíz real de Clerk.io y cachea el HTML de respaldo por clave de carrito para que la recuperación no realice llamadas API duplicadas.

Layout de escritorio y móvil #

En escritorio, el carril de recomendaciones puede situarse junto al sidecart. En móvil, muévelo al área de contenido del sidecart y muestra un producto a la vez. Usa tanto los controles deslizantes nativos de Clerk.io como controles personalizados, pero no muestres ambos juegos de flechas.

Si el diseño controla los controles, oculta los controles generados por Clerk.io dentro de este diseño:

.clerk-sidecart-recs .clerk-slider-nav,
.clerk-sidecart-recs .clerk-slider-prev,
.clerk-sidecart-recs .clerk-slider-next,
.clerk-sidecart-recs .clerk-slider-button,
.clerk-sidecart-recs [class*="clerk-slider-arrow"] {
  display: none !important;
}

Mover una raíz renderizada o reemplazar fragmentos del carrito durante la inicialización del deslizador puede dejar tarjetas de producto sin flechas visibles. Decide qué código gestiona los controles y prueba esa propiedad tras cada refresco.

Añadir al carrito #

Si las tarjetas de Recommendation tienen botones de añadir al carrito, utiliza el endpoint AJAX de la plataforma y previene la navegación normal de los enlaces. Tras el éxito, dispara el evento estándar del carrito de la plataforma si es necesario y programa una sincronización tras asentarse los cambios. Cuando Clerk.js esté disponible, registra la acción también con Clerk("cart", "add", productId, { quantity: 1 });.

Verificar el resultado #

Verifica un carrito existente y un carrito vacío. Prueba abrir y cerrar el sidecart, añadir y eliminar productos, cambiar cantidades y actualizar sin recargar toda la página.

Comprueba la colocación del carril en escritorio, integración inline en móvil, slides de un producto en móvil, carga, vacío y estados de error. Asegúrate de que no haya un placeholder vacío con solo el titular visible mientras el carrito está cargando.

En el panel de red del navegador, inspecciona las llamadas a api.clerk.io. La misma clave final de carrito no debe generar peticiones de Recommendation duplicadas y una respuesta anterior nunca debe reemplazar el set actual de recomendaciones. Por último, añade un producto recomendado desde el sidecart y verifica que el carrito, tracking y las recomendaciones se actualizan correctamente.