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 súper ligera.

Hay tres beneficios de 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.
• Suele ser más rápida, ya que tu servidor puede empezar a renderizar la página en paralelo mientras Clerk.js realiza las llamadas y muestra los resultados.
• El seguimiento de visitantes y de 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 el 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 en el 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 permite acceder a sus funcionalidades a través del objeto Clerk, y configura Clerk.js con la API key para que ya sepa para qué Store está haciendo las llamadas a la API.

Snippets #

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

Luego, utiliza los atributos del snippet para construir una llamada a la API obteniendo la API key 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>

El aspecto visual se maneja por el Diseño, el cual también es referenciado por el snippet.

Clerk.js utiliza diseños Liquid para renderizar HTML con los datos devueltos por la API. Estos se formatean como scripts, y se referencian por su ID en data-template en tu 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 pueden simplificarse para que solo incluyan una referencia a un bloque de Content, usando la sintaxis data-template="@content-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 manera sencilla desde my.clerk.io.

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

Inyección #

La inyección es una función que te permite insertar fragmentos de contenido en tu sitio web sin tener que agregarlos manualmente. Solo debes elegir un selector CSS donde inyectar el snippet, 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 cómo funciona.

ID de visitantes #

Por defecto, Clerk.js genera ID de visitantes anónimos, que se usan para rastrear 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 rastreo por mayor tiempo.

Si prefieres gestionar los ID 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 por completo estableciendo visitor como null.

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

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

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

Idioma #

Configura Clerk.js con el idioma del sitio web. Esto se utiliza para que Clerk.io gestione correctamente las reglas gramaticales en Search, y para obtener las traducciones correctas cuando uses feeds multi-idioma.

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

Los valores aceptados se encuentran en Idiomas soportados.

Funciones de diseño #

Clerk.js soporta la adición de Formatters y Globals, que pueden usarse para crear funcionalidades personalizadas de javascript en tu alcance de diseño.

Formatters #

Se utilizan para influir o cambiar atributos. Por ejemplo, quizás quieras mostrar únicamente los primeros 40 caracteres de una descripción, o tal vez necesites calcular un porcentaje de descuento específico según el tipo de cliente que haya iniciado sesión.

Globals #

Se utilizan con datos del frontend que deseas acceder en los diseños. Ejemplos pueden ser el monto restante necesario para lograr envío gratis, el nombre del cliente que inició sesión, el símbolo de la moneda o una tasa de conversión.

A continuación, 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 de manera automática en la sesión del cliente para personalizar recomendaciones de email, incluso si aún no ha 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 entrada en el sitio web y lo registra con log/email cuando un visitante escribe una dirección de correo 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 utilizan cargas de página tradicionales.

Clerk.js renderiza cualquier elemento con la clase clerk, pero pueden usarse 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 con selector personalizado a medida que el DOM cambie, siempre y cuando ya hayan sido renderizados una vez con Clerk("content", "SELECTOR").

Este comportamiento continúa hasta que se actualice toda la página.

Depuración #

Clerk.js tiene un modo de depuración integrado que registra información de diagnóstico en la consola.

Actívalo desde la consola:

Clerk("debug");

O actívalo mediante parámetros en la 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 utilizarse para mejorar la experiencia del usuario. Estas funciones suelen ahorrar tiempo de desarrollo para configuraciones personalizadas.

Instant Search #

Una parte clave de una gran experiencia de Search en e-commerce, es obtener resultados inmediatamente mientras el usuario escribe. Nuestro componente de UI Instant Search hace esta experiencia rápida y fácil de construir.

Cualquier contenido de Clerk.io puede, en teoría, convertirse en un componente de Instant Search, 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 Instant Search aquí.

Página de búsqueda #

Una parte clave de una gran experiencia de búsqueda en e-commerce es conseguir buenos resultados de búsqueda. Nuestra Search Page permite crear rápidamente una página completa con las mejores coincidencias para cualquier consulta dada.

La Search Page te permite crear una página completa que muestre 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 Search Page aquí.

Página de categoría #

Una página de categoría bien estructurada es clave para un negocio eCommerce exitoso. Nuestra Category Page permite crear rápidamente una página completa que muestre los mejores resultados 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 Category Page aquí.

Facetas #

Clerk.js viene con soporte integrado para la navegación facetada dinámica tanto para Search como para las categorías. Cualquier atributo de producto que nos envíes puede utilizarse como faceta.

Aquí hay 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 Facets aquí.

Exit Intent #

El popup de exit intent reacciona cuando un visitante intenta abandonar tu sitio desplazando el ratón hacia la parte superior de la ventana del navegador. Muestra un popup con productos interesantes, lo que puede convertir a un visitante que abandona en un cliente comprador.

Cualquier bloque de Content puede activarse con la intención de salida del visitante agregando 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 sencilla biblioteca de popups para crear fácilmente ventanas emergentes simples pero amigables con cualquier contenido. Cualquier elemento HTML en tu sitio 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í.

Excluir productos #

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

Excluir IDs específicos #

Simplemente agrega el atributo data-exclude al snippet. El contenido de data-exclude debe ser una lista de los IDs de producto que no quieres mostrar, es decir, los productos en el carrito del cliente o productos que no pueden ver.

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

Evitar duplicados #

Esto se logra agregando el atributo data-exclude-from en el bloque Clerk donde quieras eliminar el duplicado. El valor del atributo debe ser un selector CSS del otro u otros snippets para evitar 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 configuraciones más personalizadas a menudo necesitarás 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 con sesión iniciada en una configuración B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk termina de renderizar, permitiéndote obtener precios personalizados para un cliente y agregarlos a los elementos de productos:

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 Eventos aquí.

SEO y rendimiento #

Clerk.js impulsa experiencias de compra personalizadas sin ralentizar tu sitio ni perjudicar el SEO. Al utilizar renderizado del lado del cliente y una carga optimizada, equilibra velocidad, rendimiento y visibilidad en buscadores.

SEO y velocidad #

Existe el mito de que funciones de JavaScript como Clerk.js perjudican el rendimiento o el SEO. Las herramientas automáticas a menudo pasan por alto optimizaciones como almacenamiento en caché, carga en paralelo y gestión desde el servidor.

Beneficios de integración de Clerk.js #

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

Impacto en el rendimiento #

• La naturaleza ligera y asíncrona de Clerk.js usualmente implica un impacto mínimo en los tiempos de carga.
• En el mundo real el impacto suele proceder de las imágenes adicionales que se muestran en Recommendations, no del script en sí. Para minimizar el impacto:
  • Usa formatos apropiados y eficientes como WebP.
  • Redimensiona las imágenes al tamaño de display (por ejemplo, 400×400 px → 420×420 px máximo).
• Para evitar desplazamientos de diseño (CLS), reserva espacio para el contenido inyectado de Clerk.

Ejemplo:

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

Consideraciones SEO #

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

Enlazado y rastreabilidad #

• Clerk.js inyecta enlaces de Recommendations dinámicamente en el lado del cliente.
• Estos enlaces pueden mejorar el enlazado interno conectando páginas relacionadas, si los buscadores los renderizan y siguen correctamente.
• Como se inyectan por JavaScript, debes verificar cómo los rastreadores de buscadores los renderizan e interpretan.
• Los enlaces rastreados adecuadamente pueden mejorar la rastreabilidad y permitir 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 la autoridad (PageRank) entre páginas clave.
• Esto ayuda a mejorar la visibilidad y el ranking de categorías y productos.

Beneficios observados #

• Una integración correcta de Clerk.js puede correlacionarse con una estructura de enlazado interno más fuerte, lo que puede apoyar una mejor visibilidad en los resultados de búsqueda.
• Los dashboards de Clerk.io proporcionan analíticas sobre influencia de pedidos, aumento de conversiones y contribución de ingresos mediante Search, Recommendations, Email y Audience.

Prácticas recomendadas #

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