Clerk.js

Visión general #

Clerk.js es una biblioteca de JavaScript que simplifica la integración de nuestra API con el frontend. Con solo 37.7kb, es una solución súper ligera.

Hay tres beneficios al usar Clerk.js:

• Es robusto, ya que se carga de forma asíncrona. Esto significa que el resto de la página no depende de una respuesta de la API antes de cargarse.
• Suele ser más rápido, ya que tu servidor puede empezar a renderizar la página en paralelo mientras Clerk.js realiza llamadas y muestra resultados.
• El seguimiento de visitantes y clics se realiza automáticamente para cualquier resultado mostrado por Clerk. Esto no requiere cookies, ya que generamos un valor hash de la IP y useragent del visitante, combinado con una “sal” única de tienda que rota cada 30 días.

Clerk.js se carga con un script de inicialización agregado al header del sitio web:

<!-- 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_api_key'
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Este script carga la biblioteca desde nuestro CDN y permite acceder a sus funcionalidades a través del objeto Clerk, y configura Clerk.js con la clave API para que ya sepa para qué Store está haciendo llamadas API.

Snippets #

Cuando la página se carga, Clerk.js la escanea en busca de cualquier snippet con la clase “clerk”.

Luego usa los atributos del snippet para construir una llamada a la API obteniendo la clave API desde la configuración del script de inicialización.

<span
  class="clerk"
  data-api="recommendations/popular"
  data-limit="10"
  data-template="@clerk-product-template">
</span>

El aspecto visual se maneja mediante el Design, que también se referencia desde el snippet.

Clerk.js utiliza Liquid designs para renderizar HTML con los datos devueltos por la API. Estos se formatean como scripts, referenciados por su ID en data-template dentro del snippet.

<span class="clerk"
     data-api="search/search"
     data-query="jedi"
     data-limit="20"
     data-template="#clerk-template">
</span>

<script type="text/x-template" id="clerk-template">
  <h1>Resultado de Search para {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Comprar ahora</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Cargar más resultados</a>
</script>

Los snippets también se pueden simplificar para solo incluir una referencia a un bloque Element, usando la sintaxis data-template="@element-block-id":

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

Los Designs luego se gestionan con el Editor de Diseño o con código Liquid HTML de una forma sencilla desde my.clerk.io.

Tus snippets solo necesitarán contener la clase clerk, cualquier información específica de la página como ID de producto, y una referencia al ID de un bloque Element en data-template.

Inyección #

Inyección es una función que te permite insertar snippets de contenido en tu sitio web sin tener que agregarlos manualmente. En su lugar, solo eliges un Selector CSS donde inyectar el snippet, y Clerk.js lo agregará automáticamente al cargar la página.

Lee más sobre Inyección aquí.

Configuración #

Clerk.js permite varias configuraciones que modifican su funcionamiento.

IDs de visitante #

Por defecto, Clerk.js genera IDs de visitante anónimos, usados para rastrear las sesiones.

Si los clientes aceptan cookies, Clerk.js puede configurarse para colocar una cookie persistente con el ID de visitante, lo que permite un seguimiento durante un periodo más largo.

Si prefieres gestionar manualmente los IDs de sesión, puedes configurar el parámetro visitor que Clerk utiliza en las llamadas API. Alternativamente, puedes desactivar el seguimiento de sesiones configurando visitor en null.

// ID de visitante persistente
Clerk('config', {
  visitor: 'persistent'
});

// ID personalizado de visitante
Clerk('config', {
  visitor: 'ABC123'
});

// Desactivar seguimiento de visitante
Clerk('config', {
  visitor: null
});

Idioma #

Configura Clerk.js con el idioma escrito del sitio web. Esto permite que Clerk.io maneje correctamente las reglas gramaticales en Search y obtenga las traducciones correctas cuando usas feeds multilingües.

Clerk('config', {
  language: 'italian'
});

Los valores aceptados se listan en Idiomas soportados.

Funciones de Diseño #

Clerk.js soporta agregar Formatters y Globals, que se pueden usar para crear funcionalidades personalizadas de JavaScript en tus diseños.

Formatters #

Estos se usan para influir o modificar atributos. Por ejemplo, tal vez solo desees mostrar los primeros 40 caracteres de una descripción, o necesites calcular un descuento específico según el tipo de cliente conectado.

Globals #

Estos están pensados para usarse con datos frontend a los que quieras acceder en los diseños. Ejemplos incluyen el importe restante para obtener envío gratis, el nombre del cliente logueado, un símbolo de moneda o una tasa de conversión.

A continuación, un ejemplo de cómo configurar formatters y globals.

Config #

Clerk('config', {
  formatters: {
    uppercase: function(string) {
        return string.toUpperCase();
    }
  },
  globals: {
    currency_symbol: '$'
  }
});

Diseño #

<div class="name">{{ product.name | uppercase }}</div>
<div class="price">{{ currency_symbol }}{{ product.price }}</div>

Resultado #

<div class="name">GREEN LIGHT SABER</div>
<div class="price">$1999.99</div>

Seguimiento de Email #

Clerk.js puede recopilar emails automáticamente durante la sesión del cliente para personalizar recomendaciones de email incluso si todavía no han realizado una compra.

Esto se hace configurando Clerk.js con collect_email: true como se muestra aquí:

<script type="text/javascript">
  Clerk('config', {
    key: 'insert_api_key',
    collect_email: true
  });
</script>

Con esto, Clerk.js monitoreará todos los campos de input en el sitio web, y los registra con log/email cuando un visitante escribe una dirección de email en uno de ellos:

https://api.clerk.io/v2/log/email?payload={"email":"test@test.com","key":"insert_api_key","visitor":"auto"}

Renderizado personalizado #

Esto se usa principalmente con Single Page Apps (SPA), Progressive Web Apps (PWA) y otras aplicaciones que no usan cargas de página tradicionales.

Clerk.js renderiza cualquier elemento con la clase clerk, pero se pueden usar otras clases para personalizar el renderizado como selectores personalizados.

Por defecto, Clerk requiere que ejecutes Clerk("content", "SELECTOR") para renderizar el contenido cada vez que deba mostrarse.

Si agregas auto_init_custom_selectors: true a la configuración, Clerk.js inicializará automáticamente cualquier elemento de selector personalizado conforme el DOM se modifique, siempre y cuando ya hayan sido renderizados una vez con Clerk("content", "SELECTOR").

Este comportamiento continúa hasta que ocurre una recarga completa de la página.

Depuración #

Clerk.js incluye un modo de depuración que registra información diagnóstica en la consola y persiste por la sesión a través de cargas de página.

Actívalo desde la consola:

Clerk("debug");

O actívalo mediante parámetros de URL:

https://yourwebsite.com/#clerkjs:debug.level=all&debug.enable=true

Para detalles sobre la estructura de las respuestas de depuración de la API, ver Depuración de respuestas.

El depurador tiene 4 parámetros:

UI Kit #

Clerk.js incluye un conjunto de herramientas UI para elementos importantes que pueden usar para mejorar la experiencia de usuario. A menudo, esto ahorra tiempo de desarrollo para configuraciones personalizadas.

Instant Search #

Una parte clave para una gran experiencia de búsqueda ecommerce es obtener resultados inmediatamente al comenzar a escribir. Nuestro componente UI de Instant Search hace que esta experiencia sea rápida y fácil de desarrollar.

Cualquier contenido de Clerk.io puede, en teoría, convertirse en un componente Instant Search, pero funciona mejor como un desplegable que muestra resultados.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
  data-labels='["Instant Search"]'
      
  data-instant-search="INSERT_CSS_SELECTORS_HERE">
  
  <dl class="product-search-result-list">
    <dt>Productos que coinciden con <i>{{ query }}</i></dt>
    
    {% for product in products %}
      <dd class="product clerk-instant-search-key-selectable">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Comprar ahora</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Lee más sobre la herramienta UI de Instant Search aquí.

Search Page #

Una parte clave de una excelente experiencia de búsqueda ecommerce es obtener buenos resultados. Nuestra Search Page hace que esta experiencia sea rápida y fácil de construir.

Search Page te permite crear una página completa mostrando las mejores coincidencias para cualquier consulta dada.

<span 
  class="clerk"
  
  data-api="search/search"
  data-limit="40"
  data-labels='["Search Page"]'
  data-query="INSERT_QUERY_HERE"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">>
  
  <div class="product-search-result-list">
    <div>Productos que coinciden con <i>{{ query }}</i></div>
    
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Comprar ahora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostrar más resultados
    		</div>
    {% endif %}
  </div>
</span>

Lee más sobre la herramienta UI de Search Page aquí.

Category Page #

Una página de categoría bien estructurada es clave para un negocio ecommerce exitoso. Nuestra Category Page hace que esta experiencia sea rápida y fácil de construir. Esto te permite crear una página completa mostrando los mejores resultados posibles para cualquier categoría.

<span 
  class="clerk"
  
  data-api="recommendations/category/popular"
  data-limit="40"
  data-labels='["Category Page Grid"]'
  data-category="INSERT_CATEGORY_ID"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">
  
  <div class="product-category-result-list">
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Comprar ahora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostrar más resultados
    		</div>
    {% endif %}
  </div>
</span>

Lee más sobre la herramienta UI de Category Page aquí.

Facets #

Clerk.js incluye soporte integrado para navegación facetada dinámica tanto para búsqueda como para categorías. Cualquier atributo de producto que nos envíes se puede usar como facet.

Aquí tienes un ejemplo básico de uso:

<div id="clerk-search-filters"></div>

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "PRICE-TRANSLATION", "categories": "CATEGORIES-TRANSLATION", "brand": "BRAND-TRANSLATION"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="View More"
  data-facets-searchbox-text="Search for "
  data-facets-design="133995">
</span>

Lee más sobre la herramienta UI de Facets aquí.

Exit Intent #

El popup de exit intent reacciona cuando un visitante intenta dejar tu sitio al mover el mouse cerca de la parte superior de la ventana del navegador. Aparece mostrando productos interesantes, lo que puede convertir a un visitante en cliente.

Cualquier bloque Element se puede mostrar al detectar intención de salida añadiendo el atributo data-exit-intent="true" al snippet.

<span
  class="clerk"
  
  data-api="recommendations/visitor/complementary"
  data-limit="20"
  data-labels='["Exit Intent / Popup"]'
  
  data-exit-intent="true">
</span>

Lee más sobre la herramienta UI de Exit Intent aquí.

Popup #

UI Kit contiene una sencilla biblioteca de popups para crear fácilmente popups amigables con cualquier contenido. Cualquier elemento HTML en tu sitio web con la clase clerk-popup se mostrará como popup.

<div id="my-popup" class="clerk-popup">¡Hola, mundo!</div>

<script type="text/javascript">
  var my_popup = Clerk('ui', 'popup', '#my-popup');
  
  // mostrar popup
  my_popup.show(); 
  /* o */ 
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // ocultar popup
  my_popup.hide(); 
  /* o */ 
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Lee más sobre la herramienta UI de Popup aquí.

Excluir productos #

Clerk.js tiene dos formas distintas de excluir productos, dependiendo de si deseas excluir IDs específicos o evitar mostrar productos duplicados entre diferentes sliders.

Excluir IDs específicos #

Simplemente añade el atributo data-exclude al snippet. El contenido de data-exclude debe ser una lista de los IDs de productos que no quieras mostrar, por ejemplo, los productos en el carrito del cliente o productos que no puede ver.

<span class="clerk"
  data-template="@clerk-complementary"
  data-exclude="[45654, 3244, 12352]">
</span>

Evitar duplicados #

Esto se hace añadiendo el atributo data-exclude-from en el bloque Clerk donde quieras eliminar los duplicados. El valor del atributo debe ser un selector CSS de los otros snippet(s) de los que se deben evitar duplicados.

En el ejemplo siguiente, .clerk-2 excluye cualquier producto que esté en .clerk-1, y .clerk-3 excluye cualquier producto que esté en .clerk-1 o .clerk-2.

<span class="clerk clerk-1"
  data-template="@clerk-banner-1">
</span>
 
<span class="clerk clerk-2"
  data-exclude-from=".clerk-1"
  data-template="@clerk-banner-2">
</span>
 
<span class="clerk clerk-3"
  data-exclude-from=".clerk-1,.clerk-2"
  data-template="@clerk-banner-3">
</span>

Eventos #

Al construir integraciones más personalizadas, a menudo necesitarás reaccionar o modificar los resultados de Clerk antes de mostrarlos. Aquí es donde Events es útil.

Los eventos te permiten configurar listeners que ejecutan código en momentos específicos antes, durante o después de que Clerk.js renderiza sus resultados.

Un ejemplo común es cargar precios personalizados para un cliente logueado en una integración B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk termina de renderizar, permitiéndote obtener los precios personalizados para un cliente y agregarlos a los elementos de producto:

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;
    }
})

Lee más sobre los Eventos aquí.

SEO y Rendimiento #

Clerk.js potencia experiencias de compra personalizadas sin ralentizar tu sitio ni perjudicar el SEO. Utilizando renderizado del lado del cliente y carga optimizada, equilibra velocidad, rendimiento y visibilidad en motores de búsqueda.

SEO y velocidad #

Es un error común pensar que funciones JavaScript, como Clerk.js, afectan negativamente al rendimiento o al SEO. Las herramientas automatizadas a menudo pasan por alto optimizaciones como caché, carga en paralelo y manejo en el servidor.

Beneficios de integración de Clerk.js #

• El script de Clerk.js (≈ 37 - 38 KB) se carga asíncronamente, permitiendo que tu sitio se renderice mientras Clerk se inicializa.
• Los elementos de Clerk se renderizan en el cliente, por lo que tu HTML base sigue siendo cacheable, y los componentes dinámicos se inyectan solo después de la carga.
• Esto permite un uso eficiente de la caché del lado del servidor y la carga no bloqueante de los assets de Clerk.js.

Impacto en el rendimiento #

• La naturaleza ligera y asíncrona de Clerk.js normalmente implica un impacto pequeño en los tiempos de carga.
• El impacto real suele deberse a imágenes adicionales renderizadas en las recomendaciones, no al propio script. Para minimizar el impacto:
  • Usa formatos eficientes de alta calidad, como WebP.
  • Redimensiona imágenes para que coincidan con las dimensiones de visualización (ejemplo: 400×400 px → 420×420 px máx.).
• Para evitar cambios de diseño (CLS), reserva espacio para el contenido inyectado por Clerk.

Ejemplo:

.clerk-slider-wrapper {
  min-height: 300px; /* ajustar según sea necesario */
  width: 100%;
}

Consideraciones de SEO #

Entender cómo interactúa Clerk.js con los motores de búsqueda ayuda a asegurar que tu implementación favorezca la experiencia de usuario y la visibilidad en buscadores.

Enlazado e indexabilidad #

• Clerk.js inyecta enlaces de recomendación dinámicamente en el cliente.
• Estos enlaces pueden mejorar el enlazado interno conectando páginas relacionadas, si los motores de búsqueda los renderizan y siguen correctamente.
• Al ser inyectados por JavaScript, deberías verificar cómo los motores de búsqueda los renderizan e interpretan.
• Los enlaces correctamente rastreados pueden mejorar la indexabilidad y permitir a los buscadores descubrir e indexar más páginas.

Distribución de PageRank #

• Si los motores de búsqueda pueden rastrearlos, los enlaces de Clerk.js pueden ayudar a distribuir el PageRank entre páginas clave.
• Esto favorece una mejor visibilidad y posicionamiento de las páginas de producto y categoría.

Beneficios observados #

• Una correcta integración de Clerk.js puede estar relacionada con estructuras de enlazado interno más sólidas, lo que puede ayudar en una mayor visibilidad en resultados de búsqueda.
• Los dashboards de Clerk.io ofrecen analíticas sobre la influencia de pedidos, aumento de conversiones y contribuciones a ingresos desde funciones como Search, Recommendations, Email y Audience.

Prácticas recomendadas #

1. Optimiza las imágenes (formato WebP, resolución adecuada).
2. Reserva espacio en el diseño para elementos dinámicos y evitar saltos de diseño.
3. Monitorea métricas reales en vez de depender exclusivamente de herramientas automáticas. Usa los dashboards de Clerk para evaluar el impacto en todos los canales.