FAQ

¿Tienes problemas con tu integración personalizada? Este FAQ cubre los problemas más comunes y sus soluciones, desde aplicaciones de una sola página hasta el seguimiento de ventas.

Aplicaciones de una sola página #

También se denominan Progressive Web Apps (PWA) y generalmente cargan el sitio como una sola página, en lugar de cargar páginas individuales de forma habitual.

Cuando se carga una página por primera vez, la biblioteca Clerk.js dispara automáticamente una función para renderizar todos los bloques de Element en esa página.

Sin embargo, para las aplicaciones de una sola página que utilizan frameworks como vue.js o next.js, las páginas se renderizan con JavaScript en lugar de con una carga estándar de página.

Debido a esto, necesitas controlar el renderizado con Clerk.js para que se adapte a la forma en que cargas las páginas en la aplicación.

Incluir Clerk.js #

Clerk.js solo necesita cargarse una vez, cuando el sitio es cargado inicialmente.

Después de esto, la biblioteca estará disponible durante toda la sesión.

Inclúyelo justo antes del </head> en tu HTML:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
    (function(w,d){
    var e=d.createElement('script');e.type='text/javascript';e.async=true;
    e.src='https://cdn.clerk.io/clerk.js';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
    w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){w.__clerk_q.push(arguments)};
    })(window,document);

    Clerk('config', {
    key: 'INSERT_PUBLIC_API_KEY'
    });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Controlar el renderizado #

Por defecto, Clerk.js renderiza cualquier elemento que tenga la clase clerk, sin importar si ha sido insertado durante la carga inicial o cuando se muta el DOM.

Puedes controlar el momento insertando el elemento cuando esté listo para ser renderizado.

Alternativamente, puedes controlar el renderizado con la función Clerk("content", "SELECTOR").

Cada vez que se cargue una página, realiza estos pasos en orden:

• Agrega el snippet de Clerk al HTML con un selector único que puedas usar como objetivo.

• Ejecuta Clerk("content", "SELECTOR") para renderizarlo.

Cuando el visitante abandone la página, destruye el snippet y vuélvelo a renderizar si el visitante regresa a la misma página.

Esto es para asegurarte de que Clerk.js no vea el snippet como ya renderizado, evitando que se visualice.

Ejemplo:

<span 
  id="clerk-custom-snippet"
  data-template="@home-page-visitor-recommendations">
</span>

<script>
  Clerk("content", "#clerk-custom-snippet")
</script>

Clerk.js también se puede configurar para inicializar automáticamente Elements con tus selectores personalizados después de la primera vez que lo renderices.

Impacto en Pagespeed #

Agregar una herramienta externa como Clerk.js aumentará el tiempo de carga de tu sitio, pero es un aumento insignificante en comparación con las conversiones adicionales que te proporcionará.

A continuación puedes ver cómo impacta en el rendimiento de tu sitio.

Rendimiento #

La biblioteca Clerk.js solo pesa 37.5kb, así que carga muy rápido.

Además, carga los elementos de forma asíncrona, lo que significa que el resto de la página se carga mientras Clerk.js renderiza el contenido.

Un aumento en el tiempo de carga de una página suele venir de cargar más imágenes que antes, ya que los resultados de búsqueda y recomendaciones de Clerk funcionan mejor cuando son visualmente atractivos.

Para minimizar el tiempo de carga extra, recomendamos usar imágenes en formato webp con una resolución que coincida con el tamaño que tienen en los elementos de Clerk.

Por ejemplo, si las imágenes en recomendaciones tienen una resolución de 400x400px en vista de escritorio, envía imágenes con una resolución máxima de 420x420px o similar.

Google Page Speed #

Si utilizas Google Page Speed Insights u otra herramienta similar para analizar el rendimiento de tu sitio, podrías ver Clerk.js listado bajo Leverage browser caching.

El propósito de Clerk.js es hacer muy fácil insertar resultados de Clerk en cualquier sitio web.

Clerk.js contiene muchas características para gestionar el seguimiento y los componentes de la interfaz de usuario, como Instant Search, deslizadores, popups y más.

Cuando agregamos nuevas características de la interfaz de usuario o mejoramos las existentes, se incluyen en Clerk.js y deben ser descargadas por el usuario final para utilizarlas.

Tener una expiración de caché de 60 minutos significa que cuando lanzamos nuevas características estarán disponibles para todos en un máximo de 60 minutos.

Cuanto mayor sea el tiempo de caché, más tiempo se tarda en que todos tengan acceso a las funciones más recientes.

Lo importante es que los usuarios finales solo tienen que descargar Clerk.js una vez cuando hay nuevas funciones.

La expiración de caché de 60 minutos solo significa que el navegador del usuario final comprobará con Clerk cada 60 minutos.

Si no se han hecho cambios en Clerk.js, no se descargará nada.

El tiempo de expiración de cache de 60 minutos es así un equilibrio entre minimizar solicitudes web y ver nuevas funciones y mejoras.

La mayoría de las sesiones duran menos de 60 minutos, así que la solicitud solo se realizará una vez por sesión.

Como puedes ver en la captura de pantalla, esto es una práctica normal que (al igual que Clerk) es usada por Google Analytics, Facebook, Trustpilot y muchos otros.

Impacto en CLS #

El Cumulative Layout Shift (CLS) puede impactar negativamente el SEO y la experiencia del usuario cuando el contenido inyectado dinámicamente desplaza elementos en la página.

En algunos casos, entre otros factores, Clerk puede contribuir al puntaje CLS.

Puedes leer más sobre CLS aquí.

Sigue esta guía solo si tu puntuación CLS es mayor a 0.2 y los elementos de Clerk están above the fold.

Para evitar que el contenido se desplace, es necesario reservar un espacio para las recomendaciones de Clerk antes de que Clerk.js las inyecte.

Para ello, hay que añadir una altura mínima basada en la altura esperada del contenido.

Ejemplo de código:

.clerk-slider-wrapper {
    min-height: 300px; /* Ajusta según la altura esperada del contenido */
    width: 100%;
}

Realizar llamadas API #

Puedes usar Clerk.js para hacer llamadas API usando la función incorporada Clerk("call").

Esta función toma 3 argumentos:

• Un endpoint de la API

• Un diccionario JSON de parámetros

• Una función de callback para manejar la respuesta

Solicitudes #

Abajo hay un ejemplo de script que solicita los 10 productos más populares y registra la respuesta en la consola.

La respuesta contiene un objeto de JavaScript con el estado de la llamada API y el resultado.

Script #

function popularProducts(){
  Clerk("call",
    "recommendations/popular",
    {
      limit: 10,
      labels:["Home Page / Bestsellers"]
    },
    function(response){
      console.log(response);
    },
    function(response){
      console.error(response);
    }
  );
}

Respuesta #

__clerk_cb_1(
  {
    "status":"ok",
    "count":72,
    "facets":null,
    "result":[399,410,551,338,403,439,425,402,406,456]
  }
);

Callbacks #

Cuando realizas llamadas API, puedes usar funciones callback para manejar la respuesta según lo necesites.

Las funciones toman response como argumento, que contiene todos los datos devueltos por la API.

A continuación, un ejemplo que crea una lista de elementos HTML que enlazan a categorías que coinciden con la consulta “men”.

Clerk("call",
  "search/categories",
  {
      'query': "men",
      'limit': "10"
  },
  function(response) {
      var cat = response.categories;
      if (cat.length > 0) {
          let heading = document.createElement('h3');
          heading.textContent = 'Related Categories';
          document.querySelector('#your-target').append(heading);
      }
      for (var index in cat) {
          var clerkName = cat[index].name;
          var clerkUrl = cat[index].url;
          let link = document.createElement('a');
          link.href = clerkUrl;
          link.textContent = clerkName;
          document.querySelector('#your-target').append(link);
      }
  }
)

Botones de añadir al carrito #

Estos botones funcionan de manera diferente para cada plataforma y la funcionalidad puede cambiar según los plugins que utilices.

Debido a que los diseños de Clerk se componen de HTML & CSS, normalmente puedes agregar esta funcionalidad si entiendes cómo funciona en tu sitio.

Enfoque general #

Algunos botones de añadir al carrito requieren JavaScript para funcionar.

En estos casos, puedes agregar la funcionalidad al método existente cart de Clerk.

Consulta cómo hacerlo en nuestra documentación para desarrolladores aquí.

Inspecciona el botón de añadir al carrito para identificar el código asociado a él, por ejemplo, en una página de categoría.

El código habitualmente será un elemento <div> o un elemento button.

Copia todo el HTML del botón.

Copia y pega este código en tu Diseño.

Ahora debes identificar las variables en el código.

La mayoría de las veces, debes encontrar dónde el código usa:

• ID del producto

• Cantidad del producto

Reemplaza los valores del ID del producto con las variables Liquid para esos datos.

El ID siempre será {{ product.id }} y la cantidad variará dependiendo de cómo envíes los datos.

En este ejemplo podría ser {{ product.qty }}.

Pega tu código en el HTML de tu Diseño y pruébalo para asegurarte de que funciona.

Ejemplo #

El botón de añadir al carrito a continuación es un <div> que tiene la clase button-container:

La cantidad se encuentra dentro del enlace del carrito después de /cart?add= y el ID del producto está justo después de &id_product=.

El ID del producto también se referencia en data-id-product y la cantidad en .data-minimal_quantity.

Estos valores deben ser reemplazados por las etiquetas Liquid en el Diseño para que los IDs y cantidades apropiados se utilicen en el HTML resultante.

Con estos cambios, el botón final de añadir al carrito se verá así:

<div class="button-container">
  <a 
    class="button ajax_add_to_cart_button btn btn-default" 
    style="position: relative;" 
    href="https://www.examplelinktocart.com/cart?add={{ product.qty }}&amp;id_product={{ product.id }}&amp;" 
    rel="nofollow" 
    title="Add to Cart" 
    data-id-product-attribute="0" 
    data-id-product="{{ product.id }}" 
    data-minimal_quantity="{{ product.qty }}">
    <span style="color: orange !important">
      <i class="icon-shopping-cart" aria-hidden="true"></i>
    </span>
  </a>
</div>

Errores en la consola #

Clerk.js registra muchos errores en la consola, que puedes utilizar para depurar problemas.

Al hacer clic en el enlace del error obtendrás más información sobre lo que salió mal, la cual puedes utilizar para depurar el error tú mismo o enviar a nuestro equipo de soporte, que te ayudará.

A continuación encontrarás una lista de los errores más comunes.

Contenido desconocido #

Este error aparecerá si el snippet insertado hace referencia a un Element que no existe, en el atributo data-template.

Para solucionarlo, asegúrate de que el nombre en el código de inserción coincida con un bloque Element que hayas creado en my.clerk.io.

Puedes hacer clic en Edit Element en cualquier Element para ver cuál debe ser la referencia.

Endpoint API inválido #

Este error ocurre si has usado la clase clerk en algún lugar de tu HTML.

Esta clase está reservada para uso exclusivo de nuestros snippets, ya que Clerk.js la utiliza para identificar los elementos a renderizar.

Para solucionarlo, asegúrate de nombrar la clase de otra forma, como clerk-product.

Argumento de producto inválido #

Este error significa que el ID proporcionado para un producto tiene un tipo o sintaxis incorrectos.

Por ejemplo, si tus IDs de producto son enteros, también deben serlo en el código de inserción.

Además, recuerda los corchetes alrededor del ID para que sea una lista.

<span 
  class="clerk" 
  data-template="@product-page" 
  data-products="[123]">
</span>

Argumento de categoría inválido #

Este error significa que el ID proporcionado para una categoría tiene un tipo o sintaxis incorrectos.

En la mayoría de los casos, sucede si el placeholder en el código de inserción de la categoría no ha sido reemplazado por un ID real:

<span 
  class="clerk" 
  data-template="@category-page" 
  data-category="INSERT_CATEGORY_ID">
</span>

La salida del código debe contener el ID de la categoría:

<span 
  class="clerk" 
  data-template="@category-page" 
  data-category="257">
</span>

Si copiaste el snippet manualmente, asegúrate de seleccionar tu sistema de tienda en el menú desplegable Choose your platform antes de copiar el snippet.

Así cambiará para incluir la lógica de tu plataforma para seleccionar el ID de categoría correcto.

Si tu plataforma no está en la lista, debes agregar manualmente la lógica para seleccionar el ID correcto basado en la funcionalidad de tu tienda.

API key incorrecta #

Este error aparecerá si la public API key proporcionada no coincide con ninguna cuenta en Clerk.

Para corregirlo, inicia sesión en my.clerk.io y ve a Developers > API Keys.

Ahí puedes encontrar la Public API Key que puedes añadir a tu script de seguimiento Clerk.js directamente en el código o en la configuración de tu integración, según tu plataforma.

Datos de ventas POS/ERP #

Para algunas tiendas online, es relevante subir datos de ventas desde otros sistemas diferentes a la propia tienda.

Por ejemplo, si deseas optimizar el algoritmo en base a ventas de una tienda física o B2B store.

Clerk no diferencia entre pedidos de distintas fuentes; mientras puedas proporcionar un ID, un timestamp y una lista de productos vendidos, pueden subirse a Clerk.

El enfoque recomendado es usar la CRUD API, ya que te permite automatizar la tarea por completo.

Implementando estas llamadas API, puedes enviar los datos de los pedidos directamente a tu Store en Clerk.

Simplemente crea una llamada POST al endpoint /orders en tu sistema ERP o tienda, ejecuta la tarea periódicamente, por ejemplo una vez al mes, y podrás utilizar pedidos offline para potenciar recomendaciones y resultados de búsqueda online.

Alternativamente, puedes subir un archivo CSV manualmente, sin necesidad de programar nada.

Puedes leer más sobre archivos CSV aquí.

Conversión de divisas #

Existen varias formas de trabajar con la conversión de divisas en Clerk.

A continuación se detalla una forma sencilla de hacerlo funcionar.

Traducir monedas #

Si los visitantes usan Google Translate en tu tienda online, los valores de precio pueden traducirse alterando el formato o cambiando la moneda mostrada.

Para evitar esto, envuelve la salida de los precios en elementos que no deban traducirse.

Etiquetado recomendado #

Utiliza tanto translate="no" como la clase notranslate en el elemento de precio:

<span class="clerk-price notranslate" translate="no">
  {{ product.price | money }}
</span>

Si muestras precio de lista y precio de oferta, aplica el mismo patrón a cada valor de precio:

<span class="clerk-old-price notranslate" translate="no">
  {{ product.list_price | money }}
</span>
<span class="clerk-new-price notranslate" translate="no">
  {{ product.price | money }}
</span>

Aplica ubicaciones #

• En tu Diseño de Clerk donde se renderizan los precios.
• En cualquier wrapper personalizado en HTML que muestre valores de precio.

Esto mantiene el resto de la página traducible mientras se preserva el formato correcto de precio y divisa.

Enviar objetos de precios #

Clerk necesita saber los precios de cada producto en las diferentes monedas.

La forma más sencilla de hacerlo es enviarlos como un objeto JSON codificado como string de precios formateados, con el ISO de la moneda como clave, en tu Data Feed.

"products": [
  {
    "id": 1,
    "name": "Cheese",
    "description": "A nice piece of cheese.",
    "price": 100,
    "list_price": 50,
    "categories": [25, 42],
    "image": "http://example.com/images/products/1.jpg",
    "url": "http://example.com/product/1",
    "on_sale": true,
    // String-encoded JSON examples
    "prices_formatted": "{\"USD\":\"$100\", \"EUR\":\"€87.70\", \"GBP\":\"£68.68\"}",
    "list_prices_formatted": "{\"USD\":\"$120\", \"EUR\":\"€97.70\", \"GBP\":\"£78.68\"}"  
  },
  {
    "id": 2,
    "name": "A pound of nuts",
    "description": "That's a lot of nuts!",
    "price": 150,
    "categories": [1],
    "image": "http://example.com/images/products/2.jpg",
    "url": "http://example.com/product/2",
    "on_sale": false,
    // String-encoded JSON example
    "prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}",
    "list_prices_formatted": "{\"USD\":\"$150\", \"EUR\":\"€142\", \"GBP\":\"£120\"}"
  }
]

Crear formateador #

En Clerk.js puedes definir funciones JavaScript que se usen con tus Diseños.

Aquí puedes definir una función que tome tu price-dict como argumento y devuelva el precio para una moneda específica, basándose en la lógica de frontend que desees.

Asegúrate de reemplazar currency por la moneda actualmente seleccionada en el frontend.

Clerk('config', {
  key: 'Your_API_Key',
  formatters: {
      currency_selector: function (price_list) {
      const currency = "EUR";
      price_groups_obj = JSON.parse(price_list)
        return price_groups_obj[currency];
      }
  }
});

Usa el formateador #

Tras definir el formateador, puede usarse en tu diseño con esta sintaxis:

<div class="price">
   <span class="price">
      {{ product.prices_formatted | currency_selector }}
   </span>
</div>

Precios específicos por cliente #

Clerk permite mostrar diferentes precios según el cliente que haya iniciado sesión, ya sea obteniendo precios individuales al renderizar o almacenando previamente los precios de grupo en los datos del producto.

Esto se cubre en detalle en el artículo específico de Customer Pricing.

Autenticación HTTP #

La autenticación HTTP se utiliza a menudo en sitios de pruebas para evitar visitantes no deseados.

Esto, en muchos casos, también bloquea el importador de Clerk y normalmente muestra un error 401 Unauthorized en el registro de sincronización.

Puedes solucionarlo insertando la información de autenticación en la URL de importación.

En my.clerk.io > Data > Configuration, actualiza tu URL de importación así:

http://USER:PASS@www.ewoksRus.com/JSONFEED

Sin pedidos registrados #

En my.clerk.io, Tracked Orders y Order Details se fusionan en una única página de Orders.

Clerk necesita rastrear continuamente las ventas de la tienda para mantener los resultados actualizados según el comportamiento de tus clientes.

Sin embargo, algunos ajustes en una tienda pueden hacer que el seguimiento de ventas falle.

A continuación, puedes ver cómo depurar el seguimiento de ventas usando una configuración Clerk.js y los problemas y soluciones más comunes.

Antes de empezar #

Asegúrate de haber instalado:

• El script de seguimiento Clerk.js en todas las páginas.

• El script de seguimiento de ventas en tu página de éxito de pedido.

Estos son necesarios para rastrear ventas en general cuando uses una configuración Clerk.js.

Revisa los logs #

En la mayoría de los casos, el seguimiento de ventas falla por errores en los visitor IDs o product IDs de la llamada de venta enviada a Clerk tras una compra.

Para depurar esto, tendrás que hacer un pedido de prueba.

No obstante, en algunos casos puede estar relacionado con el propio script de seguimiento de ventas, y se puede depurar mirando los logs en my.clerk.io > Developers > Logs.

Si el seguimiento de ventas falla por un error en tu script, normalmente podrás ver el error en esta página.

Haz clic en Details para ver más detalles.

Si no puedes ver errores en los logs, la forma más sencilla de identificar otros problemas es hacer un pedido de prueba.

Depuración de pedido de prueba #

En este ejemplo, usamos Chrome para explicar cómo depurar el seguimiento de ventas con un pedido de prueba, pero otros navegadores tienen funciones similares.

1. En tu tienda, agrega un par de productos al carrito.

2. Ve a Checkout.

3. Antes de hacer el pedido, abre la Consola de tu navegador.

4. Ve a Network y busca “clerk”.

5. Haz el pedido para ver la página de confirmación de compra.

6. Haz clic en la llamada que comienza con sale (normalmente sale?key=…).

Aquí verás los datos enviados y recibidos por el endpoint de la API de seguimiento de ventas.

Haz clic en Preview para identificar cualquier error que pueda causar que las ventas no se rastreen.

A continuación se indican los errores más comunes con el seguimiento de ventas.

Sintaxis de productos inválida #

Este error ocurre si los IDs de producto enviados tienen una sintaxis incorrecta.

Los errores más habituales son:

• Los product-IDs están string-encoded en el seguimiento pero usas enteros en Clerk o viceversa.

• La lista de IDs de producto contiene caracteres de formato de texto en vez de un JSON puro: "products":\[\\"id"\\:\\"123-m"\\\].

Falta argumento #

Esto significa que no envías todos los datos que Clerk necesita para rastrear la venta.

Asegúrate de incluir todos los atributos de datos en el seguimiento de ventas.

No se realiza la llamada #

Si no puedes ver la llamada a sale incluso con ambos scripts instalados, es que algo ha causado que Clerk.js no se cargue correctamente.

Prueba esto siguiendo estos pasos:

1. Abre la Consola de tu navegador.

2. Escribe “Clerk”.

3. Si Clerk.js no se ha cargado correctamente verás un ReferenceError:

Uncaught ReferenceError: Clerk is not defined

Si este es el caso, revisa tu configuración de Clerk.js:

• Asegúrate de que Clerk.js esté instalado en todas las páginas.

• Asegúrate de que no esté bloqueado por otra funcionalidad JavaScript.

Bloqueo de Iubenda #

Si usas iubenda para el consentimiento de cookies (especialmente con Automatic blocking) y un visitante rechaza cookies, iubenda puede bloquear los scripts o peticiones de Clerk.

Esto normalmente significa que:

• La petición sale nunca se envía, por lo tanto el pedido no se rastrea o no se atribuye en Clerk.
• Los elementos de Clerk pueden no renderizarse, o Clerk.js puede registrar un error en consola sobre estar cargado múltiples veces (porque iubenda reescribe/pospone los scripts).

Solución: permitiendo Clerk.io en iubenda #

En iubenda, permitiendo Clerk para que no se bloquee cuando el visitante rechaza cookies.

Como mínimo, asegúrate de permitir estos dominios:

• cdn.clerk.io (Clerk.js)
• api.clerk.io (peticiones de seguimiento y ventas)

Las etiquetas exactas varían según iubenda, pero normalmente se encuentra bajo las configuraciones de Cookie Solution de tu proyecto iubenda para Automatic blocking (lista blanca/allowlist/ignore list).

Para la guía oficial de iubenda, consulta su artículo sobre bloqueo excesivo en modo de bloqueo automático: https://www.iubenda.com/en/help/153445-what-to-do-when-the-automatic-blocking-mode-is-blocking-too-much/.

Verificar la solución #

Tras actualizar los ajustes de iubenda:

1. Carga la tienda online, rechaza cookies y abre la consola del navegador.
2. Confirma que Clerk.js esté disponible (por ejemplo, typeof Clerk no debe ser "undefined").
3. Ejecuta Clerk("debug"), haz un pedido de prueba y confirma que una petición sale sea enviada a Clerk y devuelva status: "ok".

Sin impacto de Clerk #

Si consigues rastrear ventas en my.clerk.io, pero ninguna aparece como impactada por Clerk, puedes tener un error en tu configuración de visitor-tracking / click-tracking.

Comienza por asegurarte de que el visitor-tracking funciona, siguiendo estos pasos:

1. Haz clic en cualquier producto a través de Search o Recommendations de Clerk.

2. Haz un pedido con ese producto.

3. Inicia sesión en my.clerk.io y ve a Orders.

4. Espera a que el pedido aparezca.

Si el visitor-tracking funciona, verás el valor añadido por Clerk en los detalles del pedido, en la página Orders:

Si no ves ningún valor añadido en el pedido, estas son las causas más comunes:

Configuración API #

Si configuraste Clerk usando una integración personalizada directamente con la API, debes activar el visitor-tracking.

Lee cómo hacerlo en este artículo de la API.

IDs de producto incorrectos #

Para que el visitor-tracking funcione, el seguimiento de clics y de ventas deben rastrear los mismos IDs de producto que los que recibimos en el importador.

Normalmente, si esto no funciona, es porque estás rastreando los IDs de variantes en vez de los IDs padres o el SKU en vez del ID.

Para comprobar si este es el problema, haz lo siguiente:

1. En my.clerk.io, ve a Data > Orders y haz clic en el ID de un pedido que colocaste.

2. Si Clerk no puede identificar el producto, verás un ID y un placeholder de imagen.

3. Ve a Data > Products y busca el nombre del producto que agregaste. Allí podrás ver el ID esperado para el producto.

Utiliza esto para configurar tu seguimiento de ventas para usar los IDs de producto correctos.

Cambios en Visitor ID #

Clerk utiliza un visitor ID para identificar cada sesión individual, incluidos los productos que clican y compran.

Por este motivo, los IDs deberían permanecer iguales durante al menos toda la sesión y, preferiblemente, entre sesiones.

El visitor ID se crea automáticamente usando Clerk.js, pero si usas una configuración API o personalizas tus visitor IDs, podrías estar cambiándolo accidentalmente.

Este error es raro, pero puedes comprobar el visitor ID siguiendo estos pasos:

1. Abre la configuración de Network en el navegador y filtra los resultados por “clerk”.

2. Revisa cualquiera de las llamadas undefined relacionadas con search o recommendations.

3. En payload, puedes ver el Visitor ID actual. Se puede hacer con todas las llamadas asociadas con Clerk.

4. Haz clic en el producto y haz un pedido con ese producto.

5. En la página de éxito de pedido, revisa Network de nuevo y busca la llamada a sale?.

6. Asegúrate de que el visitor en payload coincida con el Visitor ID de antes.

Si no coinciden, necesitas averiguar por qué cambian.

Una causa común es que se regeneren los IDs en cada carga de página.

Actualiza tu código para usar el mismo visitor ID en cada página.

Ocultar sliders con pocos productos #

Si una categoría tiene muy pocos productos, un slider puede verse vacío o repetitivo.

Hay dos formas de gestionarlo:

Condicional en el diseño de Clerk #

Utiliza un condicional alrededor del slider para que solo se renderice cuando haya suficientes productos.

{% if products.length >= 6 %}
  <div class="clerk-slider">
    {% for product in products %}
      <!-- product card -->
    {% endfor %}
  </div>
{% endif %}

Esto es rápido de implementar, pero aún depende de la respuesta de Clerk para decidir si el slider se muestra, lo que significa que igualmente se realiza una llamada a la API, aunque el slider no se muestre.

Condicional del lado del servidor #

Si tu plataforma ya conoce el número de productos de la categoría, decide en tu plantilla si mostrar el código de inserción Clerk.

{% if category.product_count >= 6 %}
  <span class="clerk" data-template="@category-page-slider"></span>
{% endif %}

Este es el enfoque preferido porque el slider solo se inicializa cuando hay suficientes productos y el comportamiento se mantiene plenamente alineado con la lógica de conteo de tu tienda.

Actualizar a Clerk.js 2 #

Clerk.js 2 es una versión más rápida y flexible de nuestra biblioteca JavaScript.

Hace que instalar Clerk en cualquier tienda online sea más fácil.

Sin embargo, como ambas versiones funcionan de forma algo diferente, debes seguir estos pasos para actualizar con éxito.

Las dos principales diferencias en Clerk.js 2 son:

• Los Diseños en my.clerk.io usan Liquid, pero también pueden crearse fácilmente usando el Design Editor.

• El script debe insertarse justo antes del tag </head> en la plantilla de tu tienda.

Crear diseños #

Como Clerk.js 2 usa un enfoque diferente para los Diseños, necesitas crear nuevos.

Puedes crear los Diseños para Clerk.js 2 rehaciéndolos en el Design Editor o convirtiendo tu antiguo código en diseños Liquid, como se explica a continuación.

A continuación se explica cómo convertir tus antiguos code Designs a Liquid.

Opción Design Editor #

1. Ve a my.clerk.io > Recommendations/Search > Designs > New Design.

2. Selecciona un tipo de diseño distinto de Blank y asígnale un nombre. Recomendamos agregar “V2” para identificar que usas diseños Clerk.js 2.

3. En el Design Editor, haz clic en cualquiera de los elementos existentes como nombre, imagen, botón, etc. para editarlo o agrega nuevos elementos al Diseño.

4. Haz clic en Publish Design al terminar y ve al Paso 2 de la guía.

5. Ve a Recommendations/Search > Elements y cambia tu Element de Clerk para usar tu nuevo Diseño, luego haz clic en Update Element.

6. Esto hará que temporalmente no se muestren en tu tienda hasta que insertes Clerk.js 2 como se explica más abajo en esta guía.

Convertir diseños #

Como Clerk.js 2 usa el flexible lenguaje de plantillas Liquid, debes convertir los Diseños a este lenguaje.

1. Ve a my.clerk.io > Recommendations/Search > Designs > New Design.

2. Selecciona Blank > Code y asígnale un nombre. Recomendamos añadir “V2” para identificar que es un diseño Clerk.js 2.

3. Haz clic en Create Design.

4. Esto te dará un diseño en blanco con Product HTML y CSS que puedes usar.

5. Vuelve a la vista general del diseño y haz clic en Editar diseño para tu Diseño de Clerk.js 1. Recomendamos hacer esto en una nueva pestaña para que puedas copiar fácilmente el código.

6. Copia el antiguo Diseño de Clerk.js 1 a tu nuevo Diseño de Clerk.js 2.

   • Notarás que no hay Código de Contenedor en el nuevo.

   • Esto es porque Liquid utiliza bucles for para mostrar todos los productos.

   • Copia tu antiguo Product HTML dentro del bucle for, tu antiguo Código de Contenedor alrededor y copia también el CSS.

7. Convierte el Diseño a la sintaxis de Liquid. La principal diferencia es que los antiguos Diseños usaban la sintaxis {{ formatter attribute }} mientras que la sintaxis de v2 es {{ product.attribute | formatter }}.

8. Revisa todos tus atributos y cámbialos al nuevo formato.

9. Si estás utilizando sentencias {{#if}} o {{#is}}, también deben convertirse. Utiliza la sintaxis {% if product.attribute %} {% else %} {% endif %}.

10. Elimina id="{{ $id }}" y la clase :target del código de contenedor en la versión Clerk.js 2 ya que ya no son compatibles.

11. A continuación se muestra un ejemplo de un diseño Clerk.js 1 y la versión completamente convertida:

Clerk.js 1 Design #

// Product HTML
<li class="clerk-product">
    <a href="{{ url }}">
        <img src="{{ image }}" />
        <div class="clerk-product-name">{{ name }}</div>
        <div class="clerk-price-wrapper">
            {{#if list_price}}
                <div class="clerk-old-price">
                    <s>Price {{ money_eu list_price }}</s>
                </div>
                <span class="clerk-new-price">Price {{ money_eu price }}</span>
            {{else}}
                <div class="clerk-product-price">Price {{ money_eu price }}</div>
            {{/if}}
        </div>
    </a>
    <div class="clerk-cta-button btn button">Buy Now</div>
</li>

// Container Code
<h2>{{ headline }}</h2>
<ul id="{{ $id }}" class=":target clerk-slider"></ul>

<!-- This code creates the slider by its ID. -->
<script type="text/javascript">
    Clerk.ui.slider("{{ id }}").init();
</script>

Clerk.js 2 Design #

<h2>{{ headline }}</h2>

<ul class="clerk-slider">
    {% for product in products %}
    <li class="clerk-product">
        <a href="{{ product.url }}">
            <img src="{{ product.image }}" />
            <div class="clerk-product-name">{{ product.name }}</div>
            <div class="clerk-price-wrapper">
                {% if product.list_price %}
                    <span class="clerk-old-price"><s>Price {{ product.list_price | money_eu }}</s></span>
                    <span class="clerk-new-price">Price {{ product.price | money_eu }}</span>
                {% else %}
                    <div class="clerk-product-price">Price {{ product.price | money_eu }}</div>
                {% endif %}
            </div>
            <div class="clerk-cta-button btn button">Buy Now</div>
        </a>
    </li>
    {% endfor %}
</ul>

12. Haz clic en Actualizar diseño para guardar los cambios.

13. Ve a Recommendations/Search > Elements y cambia tu bloque de Elemento para usar tu nuevo Diseño.

14. Haz clic en Actualizar elemento. Esto hará que temporalmente no se muestren en tu tienda online, hasta que termines con el Paso 2. Elige el nuevo Diseño para todos los Elementos que deban actualizarse.

Reemplazar script #

1. Ubica el archivo de plantilla que se utiliza para mostrar todas las páginas de la tienda online, y donde el script original de Clerk.js se encuentra cerca de la parte inferior.

2. Elimina el antiguo script de Clerk.js del archivo. Se verá algo así:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
    window.clerkAsyncInit = function() {
        Clerk.config({
            key: 'public_api_key'
        });
    };
    (function(){
        var e = document.createElement('script'); e.type='text/javascript'; e.async = true;
        e.src = document.location.protocol + '//api.clerk.io/static/clerk.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);
    })();
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

3. Ve a my.clerk.io > Developers > Tracking Code. Aquí encontrarás el código de Clerk.js 2.

4. Copia este código, insértalo justo antes de la etiqueta </head> en la plantilla y guárdalo.

¡Felicidades! ¡Ahora estás utilizando la configuración Clerk.js 2, mucho más mejorada!

Puedes ver la documentación completa de Clerk.js 2 aquí.

Manejo de require.js #

Esta sección solo aplica al usar Clerk.js 1.

En algunas instalaciones, Require.js impide que Clerk.js se cargue, lo que significa que no aparecerán sliders ni resultados de búsqueda.

Cuando esto ocurre, aparecerá el siguiente error en tu consola:

Uncaught ReferenceError: Clerk is not defined

Hay dos formas de manejar Require.js. Ambos métodos requieren que modifiques el tracking-script que has insertado al final de todas las páginas.

Incluir en Require.js #

El mejor método es intentar que Require.js reconozca Clerk.

Puedes hacer esto insertando require(['clerk'], function() {}); al final del tracking script:

Ignorar Require.js #

Si la solución anterior no funciona, es posible ignorar Require.js.

Puedes hacerlo insertando window.__clerk_ignore_requirejs = true; en la parte superior del tracking script:

Después de usar uno de estos métodos, Require.js será compatible con Clerk.