Clerk.js

Descripció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 ultraligera.

Hay tres beneficios al usar Clerk.js:

• Es robusta, 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.
• A menudo es más rápida, ya que tu servidor puede empezar a renderizar la página en paralelo mientras Clerk.js hace llamadas y muestra resultados.
• El seguimiento de visitantes y clics se gestiona automáticamente para cualquier resultado mostrado por Clerk. Esto no requiere cookies, ya que generamos un valor hash de la IP del visitante y su useragent, combinado con una sal única de la tienda que rota cada 30 días.

Clerk.js se carga con un script de inicialización añadido 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 -->

Carga la biblioteca desde nuestro CDN y te permite acceder a sus funcionalidades a través del objeto Clerk, además de configurar Clerk.js con la clave API para que ya sepa para qué Store está haciendo las llamadas.

Fragments #

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

Luego utiliza los atributos del snippet para construir una llamada a la API, obteniendo la clave API de la configuración en el script de inicialización.

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

Los aspectos visuales se gestionan mediante el Design, al que también hace referencia el snippet.

Clerk.js utiliza diseños Liquid para renderizar HTML con los datos devueltos por la API. Estos se formatean como scripts, referenciados por su ID en data-template en tu fragmento.

<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 fragmentos también pueden simplificarse para incluir solo 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 diseños luego se gestionan con el Editor de Diseño o con código Liquid HTML de forma sencilla desde my.clerk.io.

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

Inyección #

La inyección es una función que te permite insertar snippets de contenido en tu sitio web sin tener que añadirlos manualmente. Solo tienes que elegir un selector CSS donde inyectar el fragmento, y Clerk.js lo añadirá automáticamente al cargar la página.

Lee más sobre Inyección aquí.

Configuración #

Clerk.js permite una variedad de configuraciones que cambian su funcionamiento.

IDs de visitante #

Por defecto, Clerk.js genera IDs de visitantes anónimos, utilizados para seguir las sesiones.

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

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

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

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

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

Contexto de página #

Configura Clerk.js con el contexto de la página que el visitante está viendo actualmente. Esto se utiliza para enriquecer los datos de seguimiento para funciones de personalización como Email Triggers, segmentación de Audience, y contexto de Chat.

Clerk('context', {
  product: null,  // Establece el ID del producto en las páginas de producto, p. ej. 12345 o null
  category: null, // Establece el ID de la categoría en páginas de categoría, p. ej. 67 o null
  page: null      // Establece el ID o tipo de página en otras páginas, p. ej. 'homepage' o null
});

Idioma #

Configura Clerk.js con el idioma escrito del sitio web. Esto se utiliza para que Clerk.io maneje correctamente las reglas gramaticales en Search y para obtener las traducciones correctas cuando utilices feeds multilingües.

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

Los valores aceptados se listan bajo Idiomas soportados.

Reemplaza los valores de marcador de posición con la lógica de tu plataforma para obtener los IDs dinámicamente. Cada valor debe establecerse según el tipo de página en la que se encuentre el visitante:

• product: El ID del producto mostrado en páginas de producto. Ponlo en null en páginas que no son de producto.
• category: El ID de la categoría mostrada en páginas de categoría. Ponlo en null en páginas que no son de categoría.
• page: Un identificador o tipo de página en otras páginas como la página de inicio, carrito o checkout. Ponlo en null si no aplica.

Si tu plataforma no tiene un ID específico disponible para un tipo de página, deja el valor como null. Solo establece valores para los tipos de página relevantes.

Funciones de diseño #

Clerk.js soporta la adición de Formatters y Globals, que pueden emplearse para crear funcionalidades javascript personalizadas en tus ámbitos de diseño.

Formatters #

Estos se usan para influir o cambiar atributos. Por ejemplo, podrías mostrar solo los primeros 40 caracteres de una descripción, o calcular un porcentaje de descuento específico según el tipo de cliente que ha iniciado sesión.

Globals #

Estos están pensados para usarse con datos frontend que deseas acceder en los diseños. Pueden ser, por ejemplo, el monto restante para obtener envío gratis, el nombre del cliente, un símbolo de moneda o una tasa de conversión.

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

Configuración #

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>

Salida #

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

Seguimiento de Email #

Clerk.js puede recoger emails automáticamente en la sesión del cliente para usarlos en la personalización de recomendaciones de email, incluso si aún no han realizado una compra.

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

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

Con esto, Clerk.js supervisará todos los campos de entrada en el sitio, y lo registrará con log/email cuando un visitante introduzca 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.

Agregando auto_init_custom_selectors: true a la configuración, Clerk.js inicializa automáticamente cualquier elemento selector personalizado conforme el DOM cambia, siempre y cuando haya sido ya renderizado al menos una vez con Clerk("content", "SELECTOR").

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

Depuración #

Clerk.js tiene un modo de depuración integrado que registra información de diagnóstico en la consola y se mantiene para la sesión entre cargas de página.

Actívalo desde la consola:

Clerk("debug");

O actívalo a través de parámetros en la URL:

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

Para los 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 usarse para mejorar la experiencia del usuario. Muchos de estos ahorran tiempo de desarrollo en implementaciones personalizadas.

Búsqueda instantánea #

Una parte clave de una excelente experiencia de búsqueda en e-commerce es obtener resultados al instante cuando se empieza a escribir. Nuestro componente UI de Búsqueda Instantánea hace que esta experiencia sea rápida y fácil de construir.

Cualquier contenido de Clerk.io puede convertirse en teoría en un componente de Búsqueda Instantánea, pero funciona mejor como un desplegable mostrando resultados de búsqueda.

<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 Búsqueda Instantánea aquí.

Página de búsqueda #

Una parte clave de una excelente experiencia de búsqueda en e-commerce es obtener buenos resultados. Nuestra Página de Búsqueda hace que esta experiencia sea rápida y fácil de construir.

La Página de Búsqueda te permite crear una página completa mostrando las mejores coincidencias para cualquier consulta.

<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 Página de Búsqueda aquí.

Página de categoría #

Una página de categoría bien estructurada es clave para un eCommerce exitoso. Nuestra Página de Categoría 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 Página de Categoría aquí.

Facetas #

Clerk.js viene con soporte incorporado para navegación facetada dinámica tanto para búsqueda como para categorías. Cualquier atributo de producto que nos envíes puede usarse como faceta.

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="Ver más"
  data-facets-searchbox-text="Buscar "
  data-facets-design="133995">
</span>

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

Exit Intent #

El popup de exit intent reacciona cuando un visitante intenta abandonar tu sitio moviendo el ratón cerca de la parte superior de la ventana del navegador. Aparece y muestra productos interesantes, convirtiendo posiblemente a un visitante saliente en un cliente.

Cualquier bloque Element puede activarse ante la intención de salida de un visitante 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 Exit Intent aquí.

Popup #

El UI Kit contiene una biblioteca de popups sencilla para crear fácilmente popups simples y amigables con cualquier contenido. Cualquier elemento HTML en tu web con la clase clerk-popup se mostrará como un 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 Popup aquí.

Exclusión de productos #

Clerk.js tiene dos maneras diferentes de excluir productos, dependiendo de si quieres 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 quieres mostrar, por ejemplo, los productos en el carrito del cliente o una lista de productos que no puedan 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 el duplicado. El valor del atributo debe ser un selector CSS del(los) otro(s) snippet(s) de los cuales prevenir duplicados.

En el ejemplo de abajo, .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 implementaciones más personalizadas es habitual que debas reaccionar o modificar los resultados de Clerk antes de renderizarlos. Aquí es donde los Eventos son útiles.

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

Un ejemplo común es cargar precios personalizados para un cliente autenticado en una configuración B2B. Un evento puede ejecutarse justo después de que la API de Clerk termine de renderizar, permitiéndote obtener precios personalizados para ese cliente y agregarlos a los elementos del 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 web ni afectar el SEO. Al usar renderizado en el cliente y carga optimizada, equilibra velocidad, rendimiento y visibilidad en buscadores.

SEO y velocidad #

Es un error común pensar que funciones JavaScript como Clerk.js afectan el rendimiento o el SEO. Las herramientas automáticas suelen pasar por alto optimizaciones como caché, cargas en paralelo y manejo en el servidor.

Beneficios de integración de Clerk.js #

• El script de Clerk.js (≈ 37 - 38 KB) se carga de forma asíncrona, permitiendo que tu sitio se renderice mientras Clerk se inicializa.
• Los elementos Clerk son renderizados en el cliente, por lo que tu HTML base sigue siendo susceptible de caché y los componentes dinámicos se inyectan solo después de la carga.
• Esto habilita una caché eficiente del lado del servidor y una carga no bloqueante de los recursos de Clerk.js.

Impacto en el rendimiento #

• La naturaleza asíncrona y ligera de Clerk.js suele implicar un impacto reducido en los tiempos de carga.
• El impacto real en el rendimiento suele venir de imágenes adicionales renderizadas en Recommendations, no del script mismo. Para minimizar el impacto:
  • Usa formatos de alta eficiencia y tamaño adecuado como WebP.
  • Redimensiona imágenes para que se ajusten a las dimensiones reales (p.ej., 400×400 px → 420×420 px máx).
• Para evitar saltos de diseño (CLS), reserva espacio para el contenido inyectado por Clerk.

Ejemplo:

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

Consideraciones de SEO #

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

Enlazado e indexabilidad #

• Clerk.js inyecta enlaces de Recommendations dinámicamente en el cliente.
• Estos enlaces pueden mejorar el enlazado interno, conectando páginas relacionadas, si los buscadores los renderizan y siguen correctamente.
• Como se inyectan con JavaScript, debes comprobar cómo renderizan e interpretan estos enlaces los robots de búsqueda.
• Los enlaces bien rastreados pueden mejorar la indexabilidad y realizar que los buscadores descubran e indexen más páginas.

Distribución de PageRank #

• Cuando los buscadores pueden rastrearlos, los enlaces de Clerk.js pueden ayudar a distribuir link equity (PageRank) entre las páginas clave.
• Esto respalda una mayor visibilidad y ranking de productos y categorías.

Beneficios observados #

• Una integración correcta de Clerk.js puede correlacionarse con una estructura de enlazado interno más sólida, lo que puede mejorar la visibilidad en resultados de búsqueda.
• Los paneles de Clerk.io ofrecen analíticas sobre la influencia de pedidos, mejoras en conversión y contribuciones de ingresos por Search, Recommendations, Email y Audience.

Mejores prácticas recomendadas #

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