Cualquier (webshop)

FAQ

Respuestas a preguntas frecuentes sobre integraciones personalizadas

¿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 #

Estas también son llamadas Progressive Web Apps (PWA) y, generalmente, cargan el sitio como una sola página en lugar de cargar páginas individuales de forma normal.

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

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

Debido a esto, necesitas controlar el renderizado con Clerk.js para coincidir con la forma en que cargas las páginas en la app.

Incluir Clerk.js #

Clerk.js solo necesita cargarse una vez, cuando el sitio se carga inicialmente.

Luego de esto, la biblioteca estará disponible durante toda la sesión.

Inclúyela justo antes de </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 fue insertado durante la carga inicial de la página o cuando el DOM cambia.

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 carga una página, sigue estos pasos en orden:

Añade el snippet de Clerk al HTML con un selector único al que puedas apuntar.
Ejecuta Clerk("content", "SELECTOR") para renderizarlo.

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

Esto es para asegurar que Clerk.js no vea el snippet como previamente renderizado, evitando que lo 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 puede configurarse para inicializar automáticamente Elements con tus selectores personalizados después de la primera vez que lo renderizas.

Impacto en Pagespeed #

Agregar una herramienta externa como Clerk.js aumentará el tiempo que tarda en cargar tu sitio, pero es insignificante comparado con las conversiones adicionales que proveerá.

Abajo puedes ver cómo impacta el rendimiento de tu sitio.

Rendimiento #

La librería Clerk.js solo pesa 37.5kb, así que se 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 extra de carga, recomendamos usar imágenes en formato webp con una resolución que coincida con el tamaño que tienen en los elementos Clerk.

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

Google Page Speed #

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

El propósito de Clerk.js es hacer súper sencillo insertar resultados de Clerk en cualquier sitio web.

Clerk.js contiene muchas funciones para manejar seguimiento y componentes de UI como Instant Search, sliders, popups y más.

Cuando añadimos nuevas funcionalidades de UI o hacemos mejoras a las existentes, son incluidas en Clerk.js y deben ser descargadas por el usuario final para poder utilizarlas.

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

Cuanto más largo el tiempo de caché, más tardarán todos en tener acceso a las nuevas funciones.

Lo importante es que el usuario final solo tiene que descargar Clerk.js una vez cuando las nuevas funciones estén disponibles.

La expiración de 60 minutos simplemente significa que el navegador del usuario final verificará con Clerk cada 60 minutos.

Si no hay cambios en Clerk.js, nada será descargado.

El tiempo de expiración de caché 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 hará una vez por sesión.

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

Impacto en CLS #

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

En algunos casos, entre otros factores, Clerk puede contribuir a la puntuación 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 Clerk aparecen por encima del pliegue (“above the fold”).

Para evitar el desplazamiento del contenido, es necesario reservar un espacio/placeholder para las recomendaciones de Clerk antes de que Clerk.js las inyecte.

Para lograrlo, 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 realizar llamadas a la API, usando la función incorporada Clerk("call").

Esta función recibe 3 argumentos:

Un endpoint de API
Un diccionario JSON de parámetros
Una función callback para manejar la respuesta

Solicitudes #

A continuación un script de ejemplo que solicita los 10 productos más populares y muestra la respuesta en la consola.

La respuesta contiene un objeto JavaScript con el estado de la llamada a la 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 realices llamadas API, puedes usar funciones callback para manejar la respuesta como desees.

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

A continuación, un ejemplo que crea una lista de elementos HTML con enlaces 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 diferente en cada plataforma y la funcionalidad puede cambiar dependiendo de los plugins que utilices.

Como los diseños de Clerk consisten en 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 que se ejecute JavaScript para funcionar.

En estos casos, puedes añadir 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, por ejemplo, en una página de categoría.

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

Copia todo el HTML del botón.

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

Ahora debes identificar las variables del código.

En la mayoría de los casos, tienes que encontrar dónde el código usa:

ID del producto
Cantidad del producto

Reemplaza los valores para el ID del producto por las variables Liquid correspondientes.

El ID siempre será {{ product.id }} y la cantidad puede variar según cómo envíes los datos.

Por ejemplo, aquí podría ser {{ product.qty }}.

Pega tu código en el HTML de tu Diseño y prueba para asegurarte de que funcione.

Ejemplo #

El botón de “añadir al carrito” de abajo 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 justo después de &id_product=.

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

Estos valores deben ser reemplazados por tags de Liquid en el Diseño para que los IDs y cantidades correctos se empleen en la salida HTML.

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, los cuales puedes usar para depurar problemas.

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

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

Contenido desconocido #

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

Para corregirlo, 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 para cualquier Element, para ver cuál debe ser la referencia.

Endpoint de API inválido #

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

Esta clase está reservada para su uso con nuestros snippets, ya que Clerk.js usa esta clase para identificar los elementos a renderizar.

Para solucionarlo, asegúrate de ponerle otro nombre, como clerk-product.

Argumento de producto inválido #

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

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

Además, recuerda los corchetes alrededor del ID para hacerlo 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 suministrado para una categoría tiene un tipo o sintaxis incorrectos.

En la mayoría de los casos ocurre si el placeholder en el snippet 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 desplegable Choose your platform antes de copiar el snippet.

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

Si tu plataforma no está listada, necesitas añadir manualmente la lógica para seleccionar el ID correcto de categoría en base a la funcionalidad de tu tienda.

Clave API incorrecta #

Este error aparecerá si la clave API pública que proporcionaste no coincide con ninguna cuenta en Clerk.

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

Aquí podrás encontrar la Public API Key que puedes añadir a tu script de seguimiento de Clerk.js, ya sea directamente en el código o en la configuración de tu integración, dependiendo de tu plataforma.

Datos de ventas POS/ERP #

Para algunas tiendas online, es relevante subir datos de venta de otros sistemas que no sean la propia tienda.

Por ejemplo, si quieres optimizar el algoritmo según las ventas de una tienda física o tienda B2B.

Clerk no diferencia entre pedidos de distintas fuentes, siempre que puedas proporcionar un ID, una marca de tiempo y una lista de productos vendidos, pueden subirse a Clerk.

La forma recomendada es usar la CRUD API ya que permite automatizar totalmente la tarea.

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

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

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

Puedes leer más acerca de los archivos CSV aquí.

Conversión de divisas #

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

Una manera simple de hacerlo se describe a continuación.

Traducir monedas #

Si los visitantes usan Google Translate en tu tienda online, los valores de precios pueden traducirse de formas que rompan el formato o cambien la visualización de la moneda.

Para evitar esto, envuelve la salida del precio en elementos que no deban ser traducidos.

Marcado 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 en oferta, aplica el mismo patrón a cada valor:

<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>

Aplicar ubicaciones #

En tu Diseño Clerk donde se muestran los precios.
En cualquier wrapper HTML personalizado que muestre valores de precios.

Esto permite traducir el resto de la página mientras se preserva el formato correcto de precios y moneda.

Enviar objetos de precios #

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

La forma más sencilla es enviarlos como un JSON stringificado de precios formateados, usando 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 pueden usar con tus Diseños.

Aquí puedes definir una función que reciba tu price-dict como argumento y devuelva el precio para una moneda específica, según la lógica del frontend que desees.

Asegúrate de reemplazar currency con 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];
      }
  }
});

Usar formateador #

Después de definir el formateador, puedes usarlo en tu diseño con la siguiente sintaxis:

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

Precios específicos por cliente #

Para mostrar precios exclusivos en base al cliente autenticado, crea un Event en Clerk que inserte el precio correcto antes de que los productos sean renderizados.

Events son funciones JavaScript que se ejecutan antes o después de que Clerk muestra productos.

Este método puede usarse si puedes consultar precios en tu servidor, directamente desde una función JavaScript, en el frontend basado en ID de producto y ID de cliente.

Para mostrar precios individuales por cliente, el código debe ejecutarse justo después de la respuesta.

A continuación, un ejemplo de un evento simple.

<span class="clerk" data-template="@home-page-popular"></span>

<script>
  Clerk('on', 'response', function(content, data) {
     console.log(data.result);
  });
</script>

La función recibe el argumento data que es toda la respuesta que Clerk envía desde la API.

Precios individuales por cliente #

Si necesitas mostrar precios totalmente únicos según el cliente autenticado, debes configurar un Event que inserte el precio correcto después de que los productos sean renderizados.

Los eventos son funciones JavaScript ejecutadas antes o después de que Clerk muestra productos.

Este enfoque asume que puedes consultar los precios en tu servidor mediante una llamada AJAX en el frontend en base, por ejemplo, a ID de producto y ID de cliente.

La mejor forma es primero crear un contenedor placeholder de precio en tu diseño y luego reemplazarlo con el precio devuelto por tu llamada AJAX.

Un ejemplo:

<div class="clerk-price-container">
   <span class="clerk-price">
      Loading price...
   </span>
</div>

Luego puedes usar el evento de Clerk para esperar a que los productos sean renderizados, hacer una solicitud a tu servidor de precios utilizando el ID del producto y el del cliente, antes de reemplazarlo en el HTML.

Aquí tienes un ejemplo de cómo hacerlo:

<script>
  var customer_id = INSERT_CUSTOMER_ID;
  Clerk("on", "rendered", function(content, data){
    for (i = 0; i < data.product_data.length; i++) {
        var product = data.product_data[i];
          var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
          let price_container = document.querySelector(`[data-clerk-product-id='${product.id}'] .clerk-price`);
          price_container.innerText = custom_price;
      }
  })
  </script>

El código asume que puedes identificar un cliente autenticado con INSERT_CUSTOMER_ID y que tienes una función como FETCH_PRICE_FROM_SERVER que devuelve el precio según el cliente.

price_container se usa para identificar el producto correcto según el ID disponible en data-clerk-product-id, que es añadido a todos los productos por Clerk.js.

Finalmente, reemplaza el texto interno, “Loading price…” en este ejemplo, por el precio devuelto en la llamada AJAX.

Precios por grupo de clientes #

La configuración de precios por grupo de clientes consiste en 4 pasos:

Incluye los distintos precios en el data feed.
Incluye una variable global que obtenga el ID del grupo de clientes actual.
Crea una función para obtener el precio relevante.
Muestra el precio en el Diseño.

Incluir objetos de precio #

Comienza añadiendo un atributo a todos los productos que contenga todas las opciones de precio disponibles, correlacionando cada precio con un grupo de clientes particular.

Esto debe enviarse como un objeto JSON. Ejemplo:

"customer_group_prices": {
  "GROUP1": 100,
  "GROUP2": 202,
  "GROUP3": 309
}

Variable de ID de cliente #

Añade una variable global dinámica a Clerk.js, que obtenga el ID de grupo de clientes del cliente actual y lo añada como valor.

El ID de Grupo de Clientes debe equivaler a la clave de su precio correspondiente en el Data Feed.

Por ejemplo, si un usuario debe ver el precio de grupo 2, el ID debe ser “GROUP2”.

Clerk('config', {
  globals: {
    customer_group: "GROUP2"
  }
});

Obtener el precio #

Ahora puedes crear un Formatter, que reciba customer_group como argumento y retorne el precio relevante.

Haz esto escribiendo una función que obtenga el precio del grupo de clientes como la clave del price-dict en base al ID de customer_group.

Agrega esto en la configuración de Clerk.js. Ejemplo llamado getPrice:

Clerk('config', {
  globals: {
    customer_group: "GROUP2"
  },
  formatters: {
    getPrice: function (prices, customer_group) {
      return prices[customer_group];
    }
  }
});

Mostrar precio #

Cuando el formateador getPrice está creado, lo puedes usar directamente en tu Diseño junto con la lista customer_group_prices creada en el paso 1:

<li style="text-align: center; width: 180px;">
	<a href="{{ product.url }}">
		<img src="{{ product.image }}" />
		{{ product.name }}
	</a>
	<div class="price">
		{{ product.customer_group_prices | getPrice customer_group }}
	</div>
</li>

Autenticación HTTP #

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

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

Puedes solucionar esto 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

No hay pedidos rastreados #

En my.clerk.io, Tracked Orders y Order Details se combinan en una sola página de Orders.

Clerk necesita rastrear continuamente las ventas del webshop para mantener los resultados actualizados con el comportamiento de tus clientes.

Sin embargo, algunas configuraciones en un webshop pueden hacer que el rastreo de ventas falle.

Abajo, descubre cómo depurar el rastreo de ventas utilizando Clerk.js y ver los problemas y soluciones más habituales.

Antes de empezar #

Asegúrate de tener instalados:

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 usas una configuración Clerk.js.

Verificar logs #

En la mayoría de los casos, el rastreo de ventas falla por errores de los IDs de visitante o producto en la llamada de venta enviada a Clerk después de la compra.

Para depurarlo, deberás realizar un pedido de prueba.

Pero, en algunos casos puede estar relacionado con el propio script de rastreo y puede depurarse revisando los logs en my.clerk.io > Developers > Logs.

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

Haz clic en Details para ver más.

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

Depuración de pedidos de prueba #

En este ejemplo, usamos Chrome para mostrar cómo depurar el rastreo de ventas con un pedido de prueba, pero otros navegadores ofrecen características similares.

En tu tienda online, pon un par de productos en el carrito.
Procede a Checkout.
Antes de hacer el pedido, abre la Consola de tu navegador.
Busca Network, y filtra por “clerk”.
Realiza el pedido, así verás la página de confirmación de pedido.
Haz clic en la llamada que comienza con sale (normalmente sale?key=…).

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

Haz clic en Preview para identificar cualquier error que cause que las ventas no sean rastreadas.

Abajo se muestran errores comunes asociados al rastreo de ventas.

Sintaxis de productos inválida #

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

Los errores más comunes son:

Los IDs de producto están codificados como strings en el rastreo, pero usas Enteros en Clerk o viceversa.
La lista de IDs contiene caracteres de formato de texto en vez de JSON puro: "products":\[\\"id"\\:\\"123-m"\\\].

Falta un argumento #

Esto significa que no estás enviando todos los datos que Clerk necesita para rastrear la venta.

Asegúrate de incluir todos los atributos necesarios en el rastreo de ventas.

No se realiza la llamada #

Si no ves la llamada a sale aun teniendo ambos scripts instalados, algo hizo que Clerk.js se cargue de forma incorrecta.

Prueba esto siguiendo estos pasos:

Abre la Consola en tu navegador.
Escribe “Clerk”.
Si Clerk.js no se ha cargado correctamente, verás un ReferenceError:

Uncaught ReferenceError: Clerk is not defined

En ese 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 otro JavaScript.

Bloqueo por Iubenda #

Si usas iubenda para consentimiento de cookies (especialmente con Bloqueo automático) y un visitante rechaza las cookies, iubenda puede bloquear los scripts o peticiones de Clerk.

Esto suele significar que:

La petición sale nunca se envía, por lo que el pedido no se rastrea ni se atribuye en Clerk.
Los elementos Clerk pueden no renderizarse, o Clerk.js puede registrar un error en consola sobre carga múltiple (ya que iubenda reescribe/difiere scripts).

Solución: incluir Clerk.io en la lista permitida de iubenda #

En iubenda, pon Clerk en la allowlist para que no se bloquee cuando el visitante rechace cookies.

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

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

Las etiquetas de UI exactas varían en iubenda, pero usualmente se encuentra en las opciones Cookie Solution para Automatic blocking (allowlist/whitelist/ignore list).

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

Verifica la solución #

Después de actualizar la configuración de iubenda:

Accede al webshop, rechaza cookies y abre la consola.
Confirma que Clerk.js está disponible (por ejemplo, typeof Clerk no debe ser "undefined").
Ejecuta Clerk("debug"), realiza un pedido de prueba y verifica que se envía una petición sale a Clerk y retorna status: "ok".

Sin impacto de Clerk #

Si logras rastrear ventas en my.clerk.io, pero ninguna aparece como impactada por Clerk, podrías tener un error en tu configuración de rastreo de visitantes / clics.

Primero, asegúrate de que el visitor-tracking funcione, haciendo lo siguiente:

Haz clic en cualquier producto desde el Search o las Recommendations de Clerk.
Realiza un pedido que incluya dicho producto.
Inicia sesión en my.clerk.io y ve a Orders.
Espera a que aparezca el pedido.

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

Si no ves valor añadido en el pedido que hiciste, las siguientes secciones presentan errores comunes que pueden causarlo.

Configuraciones API #

Si configuraste Clerk con una integración personalizada usando la API directamente, necesitas habilitar activamente el visitor-tracking.

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

IDs de producto incorrectos #

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

Usualmente, si esto no funciona es porque estás rastreando IDs de variante en vez de IDs de producto principal o el SKU en vez del ID.

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

En my.clerk.io, ve a Data > Orders y haz clic en el ID de un pedido realizado.
Si Clerk no puede identificar el producto, verás un placeholder de ID e imagen.
Ve a Data > Products y busca el nombre del producto que agregaste. Aquí podrás ver el ID esperado para el producto.

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

Cambios en el ID de visitante #

Clerk utiliza un visitor ID para identificar cada sesión individual, incluyendo los productos en los que hacen clic y compran.

Por este motivo, los IDs deben permanecer iguales durante al menos toda la sesión y, preferiblemente, también en varias sesiones.

Este visitor ID se crea automáticamente cuando utilizas Clerk.js para la configuración, pero si usas una configuración mediante API, o personalizas tus visitor IDs, podrías cambiarlo accidentalmente.

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

Abre la configuración de Network en el navegador y filtra los resultados buscando “clerk”.
Comienza revisando cualquiera de las llamadas a undefined que estén relacionadas con search o recommendations.
En el payload puedes consultar el Visitor ID actual. Podrás hacerlo para todas las llamadas asociadas con Clerk.
Haz clic en el producto y realiza un pedido con este producto.
En la página de Order Success, revisa Network nuevamente y encuentra la llamada a sale?.
Asegúrate de que visitor en el payload coincide con el Visitor ID que viste en el paso 3.

Si los IDs de visitor no coinciden, necesitas averiguar por qué están cambiando.

Una causa habitual de que cambien los visitor IDs podría ser si regeneras los IDs en cada nueva página que se carga.

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 manejar esto:

Condicional de Clerk Design #

Usa un condicional alrededor del marcado del slider para que solo se muestre cuando se devuelvan 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 debe ser visible. Esto significa que sigue costando una llamada a la API incluso cuando el slider no se muestra.

Condicional del lado del servidor #

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

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

Este es el método preferido porque el slider solo se inicializa cuando hay suficientes productos y el comportamiento se mantiene totalmente alineado con la lógica de conteo de categorías de tu tienda en línea.

Actualizar a Clerk.js 2 #

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

Hace que instalar Clerk en cualquier tienda en línea sea más fácil.

Sin embargo, dado que las dos versiones funcionan de forma ligeramente diferente, debes seguir estos pasos para actualizar correctamente.

Las dos principales diferencias en Clerk.js 2 son:

Los Designs en my.clerk.io utilizan Liquid, pero también pueden crearse fácilmente usando el Design Editor.
El script debe insertarse justo antes de la etiqueta </head> en la plantilla de tu tienda.

Crear diseños #

Como Clerk.js 2 tiene un enfoque diferente para los Designs, debes crear nuevos.

Puedes crear tus Designs de Clerk.js 2 rehaciéndolos en el Design Editor o convirtiendo tus antiguos Designs en código a Liquid, como explica la guía a continuación.

A continuación se describe cómo convertir tus antiguos Designs en código a Liquid.

Opción de Design Editor #

Ve a my.clerk.io > Recommendations/Search > Designs > New Design.
Selecciona un tipo de design distinto de Blank y asígnale un nombre. Recomendamos añadir “V2” para que sea obvio que utilizas diseños de Clerk.js 2.
En el Design Editor, haz clic en cualquiera de los elementos existentes como el nombre, imagen, botón, etc. para editarlos o añade nuevos elementos al Design.
Haz clic en Publish Design cuando termines y ve al Step 2 en la guía.
Ve a Recommendations/Search > Elements y cambia tu Clerk Element para utilizar tu nuevo Design, luego haz clic en Update Element.
Esto provocará que temporalmente no se muestre en tu tienda hasta que insertes Clerk.js 2 como se describe más abajo en esta guía.

Conversión de diseños #

Dado que Clerk.js 2 utiliza el lenguaje Liquid, debes convertir los Designs a este lenguaje.

Ve a my.clerk.io > Recommendations/Search > Designs > New Design.
Selecciona Blank > Code y asígnale un nombre. Recomendamos añadir “V2” para que sea obvio que utilizas diseños de Clerk.js 2.
Haz clic en Create Design.
Esto te dará un diseño en blanco con HTML y CSS de producto que puedes utilizar.
Vuelve a la vista general de diseños y haz clic en Edit Design de tu Design de Clerk.js 1. Te recomendamos hacerlo en una nueva pestaña para poder copiar el código fácilmente.
Copia el código de tu antiguo Design de Clerk.js 1 a tu nuevo Design de Clerk.js 2.
- Notarás que no hay Container Code en el nuevo.
- Esto es porque Liquid usa for loops para mostrar todos los productos.
- Copia tu antiguo Product HTML dentro del for-loop, tu antiguo Container Code alrededor y copia también el CSS.
Convierte el Design a la sintaxis de Liquid. La principal diferencia es que los antiguos Designs usaban la sintaxis {{ formatter attribute }}, mientras que la de v2 es {{ product.attribute | formatter }}.
Revisa todos tus atributos y cámbialos al nuevo formato.
Si estás usando sentencias {{#if}} o {{#is}}, también debes convertirlas. Utiliza la sintaxis {% if product.attribute %} {% else %} {% endif %}.
Elimina id="{{ $id }}" y la clase :target del código del contenedor en la versión Clerk.js 2 ya que ya no son compatibles.
A continuación, un ejemplo de un diseño Clerk.js 1 y la versión totalmente 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>

Haz clic en Update Design para guardar los cambios.
Ve a Recommendations/Search > Elements y cambia tu bloque Element para que use tu nuevo Design.
Haz clic en Update Element. Esto provocará que temporalmente no se muestre en tu tienda hasta que finalices el Step 2. Elige el nuevo Design para todos los Elements que deban actualizarse.

Sustituir el script #

Ubica el archivo de plantilla que se usa para mostrar todas las páginas de la tienda y donde el script original de Clerk.js se encuentra cerca de la parte inferior.
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 -->

Ve a my.clerk.io > Developers > Tracking Code.. Aquí encontrarás el código de Clerk.js 2.
Copia este código, insértalo justo antes de la etiqueta </head> en la plantilla y guárdalo.

¡Felicidades! ¡Ahora estás usando la configuración mejorada de Clerk.js 2!

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

Manejo de require.js #

Esta sección solo aplica cuando usas Clerk.js 1.

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

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

Uncaught ReferenceError: Clerk is not defined

Hay dos formas de manejar Require.js. Ambas requieren que modifiques el tracking-script que has insertado en la parte inferior 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; al inicio del tracking script:

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

Esta página ha sido traducida por una IA útil, por lo que puede contener errores de idioma. Muchas gracias por su comprensión.