Cualquier (tienda en línea)

Clerk.js

Integra Clerk.io en cualquier frontend con una biblioteca JS ligera.

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 extremadamente ligera.

Hay tres beneficios al utilizar Clerk.js:

Es robusto, ya que se carga de forma asíncrona. Esto significa que el resto de la página no depende de la respuesta de una API para cargar.
A menudo es más rápido, ya que tu servidor puede empezar a renderizar la página en paralelo mientras Clerk.js realiza llamadas y renderiza 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 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 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, y configura Clerk.js con la clave de la API para que ya sepa para qué Store está haciendo llamadas a la API.

Snippets #

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

Luego utiliza los atributos del snippet para construir una llamada a la API mientras obtiene la clave de API de la configuración del script de inicialización.

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

Los elementos visuales son gestionados por el Diseño, que 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, referenciados 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>Search result for {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Buy Now</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Load More Results</a>
</script>

Los snippets también pueden simplificarse para incluir solo una referencia a un bloque Content, usando la sintaxis data-template="@content-block-id":

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

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

Tus snippets solo tendrán que contener la clase clerk, cualquier información específica de la página como IDs de producto, y una referencia al ID de un bloque Content 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 agregarlos manualmente. En su lugar, solo eliges un selector CSS donde se inyectará el snippet, y Clerk.js lo añadirá automáticamente al cargar la página.

Lee más sobre la Inyección aquí.

Configuración #

Clerk.js permite varias configuraciones que cambian cómo funciona.

Visitor IDs #

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

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

Si prefieres gestionar los IDs de sesión manualmente, puedes configurar el parámetro visitor que Clerk utiliza en las llamadas a la API. Alternativamente, puedes desactivar completamente el seguimiento de sesión 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
});

Idioma #

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

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

Los valores aceptados se encuentran en Idiomas soportados.

Funciones de Diseño #

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

Formatters #

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

Globals #

Están pensados para usarse con datos de frontend a los que quieras acceder en los diseños. Esto podría ser ejemplos como la cantidad restante para conseguir el envío gratis, el nombre de un cliente conectado, el símbolo de una moneda o una tasa de conversión.

A continuación hay un ejemplo de configuración de 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 personalizar recomendaciones de email incluso si aún no han realizado una compra.

Esto se realiza 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 monitorizará todos los campos de input en el sitio web, y los registrará con log/email cuando un visitante escriba 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 utiliza 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 se pueden usar otras clases para personalizar el renderizado como selectores personalizados.

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

Agregando auto_init_custom_selectors: true a la configuración, Clerk.js inicializará automáticamente cualquier elemento de selector personalizado a medida que el DOM cambie, siempre que ya se haya renderizado una vez con Clerk("content", "SELECTOR").

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

Depuración #

Clerk.js tiene un modo de depuración incorporado que registrará información en la consola, dependiendo del nivel que elijas. Se configura directamente en la URL:

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

El depurador tiene 4 parámetros:

Config	Función	Tipo
`level`	Define el nivel de log. Puede ser `log`, `warn` o `error`. El nivel por defecto es `warn`.	`string`
`collect`	Define si el logger debe usar el almacenamiento del navegador o almacenamiento temporal para guardar mensajes de log. Por defecto es `true`.	`bool`
`enable`	Activa los mensajes de depuración de Clerk en la consola del navegador. Por defecto es `true`.	`bool`
`clear`	Borra los mensajes de log.	`bool`

UI Kit #

Clerk.js incluye un conjunto de herramientas de UI para elementos importantes que pueden usarse para mejorar la experiencia del usuario. Estas a menudo ahorran tiempo de desarrollo en configuraciones personalizadas.

Instant Search #

Una parte clave de una gran experiencia de Search en e-commerce es obtener resultados de inmediato al comenzar a escribir. Nuestro componente de UI Instant Search hace que esta experiencia de usuario sea rápida y fácil de construir.

Cualquier contenido de Clerk.io puede teóricamente convertirse en un componente 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>Products matching <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 }}">Buy Now</a>
      </dd>
    {% endfor %}
  </dl>
</span>

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

Search Page #

Una parte clave de una gran experiencia de búsqueda en e-commerce es obtener buenos resultados de búsqueda. Nuestra Search Page hace que esta experiencia de usuario sea rápida y fácil de construir.

La 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>Products matching <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 }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

Lee más sobre la herramienta de UI 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 de usuario sea rápida y fácil de construir. Esto te permite crear una página completa mostrando 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 }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

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

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

Aquí tienes un ejemplo de uso básico:

<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 de UI Facets aquí.

Exit Intent #

El popup de exit intent reacciona cuando un visitante intenta salir de tu sitio moviendo el ratón cerca de la parte superior de la ventana del navegador. Se muestra y enseña productos interesantes, pudiendo convertir un visitante que iba a salir en un cliente comprador.

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

El UI Kit contiene una biblioteca simple de popup para crear fácilmente popups sencillos pero amigables para el usuario 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">Hello, world!</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 de UI Popup aquí.

Excluir productos #

Clerk.js ofrece dos formas diferentes 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 IDs de producto que no deseas mostrar, por ejemplo, los productos en el carrito del cliente o una lista de productos que no están permitidos para dicho usuario.

<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 de Clerk donde quieras eliminar el duplicado. El valor del atributo debe ser un selector CSS para el/los otro(s) snippet(s) del que se quiera evitar duplicados.

En el siguiente ejemplo, .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 escuchas de eventos 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 conectado en una configuración B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk termine de renderizar, permitiéndote obtener precios personalizados para un cliente y añadirlos 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 afectar el SEO. Usando renderizado del lado del cliente y carga optimizada, equilibra velocidad, rendimiento y visibilidad en buscadores.

SEO y velocidad #

Es un error pensar que las funciones JavaScript como Clerk.js perjudican el rendimiento o el SEO. Las herramientas automatizadas a menudo pasan por alto optimizaciones como caché, carga paralela y gestión del lado del servidor.

Beneficios de la 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 de Clerk se renderizan en el cliente, por lo que tu HTML base sigue siendo cacheable y los componentes dinámicos solo se inyectan tras 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 normalmente tiene poco impacto en los tiempos de carga de página.
El impacto real en el rendimiento suele deberse a las imágenes adicionales renderizadas en recomendaciones, no al script. Para minimizar ese impacto:
- Usa formatos de alta eficiencia y tamaño adecuado como WebP.
- Redimensiona imágenes para que coincidan con las dimensiones de visualización (ej: 400×400 px → 420×420 px máximo).
Para evitar cambios de diseño (CLS), reserva espacio para el contenido Clerk inyectado.

Ejemplo:

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

Consideraciones SEO #

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

Enlazado e Indexabilidad #

Clerk.js inyecta enlaces de recomendaciones 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 mediante JavaScript, deberías comprobar cómo los rastreadores de buscadores los renderizan e interpretan.
Los enlaces correctamente rastreados pueden mejorar la descubierta e indexación de páginas.

Distribución de PageRank #

Si los buscadores pueden rastrearlos, los enlaces de Clerk.js pueden ayudar a distribuir autoridad (PageRank) entre las páginas clave.
Esto favorece la visibilidad y el ranking de páginas de producto y categorías.

Beneficios Observados #

Una correcta integración de Clerk.js puede correlacionarse con estructuras internas de enlaces más sólidas, lo que apoya una mejor visibilidad en resultados de búsqueda.
Los dashboards de Clerk.io ofrecen analíticas sobre la influencia en pedidos, aumento de conversiones y contribución a ingresos de Search, Recommendations, Email y Audience.

Mejores Prácticas Recomendadas #

Optimiza las imágenes (formato WebP, resolución correcta).
Reserva espacio de layout para elementos dinámicos y evita cambios de diseño.
Monitorea métricas reales en vez de confiar solo en puntuaciones automáticas. Usa los dashboards de Clerk para evaluar el impacto en todos los canales.

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

Clerk.js

Visión general #

Snippets #

Inyección #

Configuración #

Visitor IDs #

Idioma #

Funciones de Diseño #

Formatters #

Globals #

Configuración #

Diseño #

Salida #

Seguimiento de Email #

Renderizado Personalizado #

Depuración #

UI Kit #

Instant Search #

Search Page #

Category Page #

Facets #

Exit Intent #

Popup #

Excluir productos #

Excluir IDs específicos #

Evitar Duplicados #

Eventos #

SEO y Rendimiento #

SEO y velocidad #

Beneficios de la integración de Clerk.js #

Impacto en el Rendimiento #

Consideraciones SEO #

Enlazado e Indexabilidad #

Distribución de PageRank #

Beneficios Observados #

Mejores Prácticas Recomendadas #