Cualquier (webshop)

Clerk.js

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

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 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 cargar.
Suele ser más rápido, ya que tu servidor puede comenzar a renderizar la página en paralelo con Clerk.js realizando llamadas y mostrando 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 en hash de la IP del visitante y del useragent, combinado con un salt único de 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, configurando Clerk.js con la clave API de modo que ya sabe para qué tienda realiza las 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 usa los atributos del snippet para construir una llamada API y obtener la clave desde el config 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 gestiona a través del Diseño, que también es referenciado por el snippet.

Clerk.js utiliza Liquid designs para renderizar HTML con los datos retornados 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>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 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>

Luego, los diseños se gestionan con el Design Editor o con Liquid HTML code de manera amigable desde my.clerk.io.

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

Inyección #

Injection es una función que te permite insertar snippets de contenido en tu sitio sin tener que hacerlo manualmente. Simplemente eliges un Selector CSS para inyectar el snippet, y Clerk.js lo agregará automáticamente al cargar la página.

Lee más sobre Injection aquí.

Configuración #

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

IDs de visitante #

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

Si los clientes aceptan cookies, Clerk.js puede configurarse para colocar una cookie persistente con el visitor ID, permitiendo rastreo durante períodos más largos.

Si prefieres gestionar los session IDs manualmente, puedes configurar el parámetro visitor que Clerk usa en llamadas a la API. Alternativamente, puedes desactivar totalmente el seguimiento de sesiones configurando visitor a null.

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

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

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

Contexto de página #

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

Clerk('context', {
  product: null,  // Asigna el ID de producto en páginas de producto, ej. 12345 o null
  category: null, // Asigna el ID de categoría en páginas de categoría, ej. 67 o null
  page: null      // Asigna el ID o tipo de página en otras páginas, ej. 'homepage' o 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 busque las traducciones correctas si usas multi-language feeds.

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

Los valores aceptados están listados en Supported languages.

Reemplaza los valores de ejemplo 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 visualizado en páginas de producto. Asignar null en páginas que no son de producto.
category: El ID de la categoría visualizada en páginas de categoría. Asignar null si no es página de categoría.
page: Identificador de página o cadena de tipo de página, en páginas como inicio, carrito, o checkout. Asignar 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 configura valores para los tipos de página que sean relevantes.

Funciones de diseño #

Clerk.js permite añadir Formatters y Globals, que pueden usarse para crear funcionalidades javascript personalizadas para tus diseños.

Formatters #

Se usan para influir o cambiar atributos. Por ejemplo, solo mostrar los primeros 40 caracteres de una descripción, o calcular un porcentaje de descuento específico según el tipo de cliente conectado.

Globals #

Están destinados a usarse con datos frontend que quieras acceder en los diseños. Algunos ejemplos: el monto restante para envío gratis, el nombre del cliente conectado, el símbolo de la moneda o una tasa de conversión.

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

Resultado #

<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 aunque no hayan hecho un pedido aún.

Activa collect_email en tu configuración de Clerk.js:

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

Con esto activado, Clerk.js monitorea los campos de email y automáticamente envía log/email cuando un visitante introduce una dirección de correo.

Si quieres registrar un email de forma manual, también puedes agregar un snippet así:

<span class="clerk" data-api="log/email" data-email="EMAIL@EXAMPLE.COM"></span>

Cómo funciona la asociación #

Cuando se registra un email, Clerk envía tanto el visitor ID como la dirección de correo a la API para que puedan ser conectados.

Esto permite que Clerk identifique lo que ese visitante ha hecho en su historial de sesión (por ejemplo productos vistos, clics, búsquedas) y asocie ese comportamiento con el correo electrónico.

Con esa asociación, el mismo comportamiento puede usarse para casos de uso de email (como envíos desencadenados y personalizados) y para personalización onsite en recomendaciones para clientes conectados.

Renderizado personalizado #

Esto es principalmente usado 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 contenido cada vez que deba mostrarse.

Si añades auto_init_custom_selectors: true en la configuración, Clerk.js inicializará automáticamente cualquier selector personalizado conforme el DOM cambie, siempre que haya sido ya renderizado alguna 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 debug integrado que registra información diagnóstica en la consola del navegador. Guarda su configuración en sessionStorage bajo la clave __clerk_debug, manteniendo el modo debug activo al navegar dentro de la misma sesión del navegador.

Por defecto, el modo debug se activa con level en warn y collect en true.

Métodos de activación #

Existen tres formas de activar el modo debug.

Shorthand de consola

La forma más sencilla es llamar a Clerk('debug') desde la consola del navegador. Acepta varios formatos de argumento:

Clerk('debug');              // Activa con valores predeterminados
Clerk('debug', true);        // Activa
Clerk('debug', false);       // Desactiva
Clerk('debug', 'on');        // Activa
Clerk('debug', 'off');       // Desactiva
Clerk('debug', 'warn');      // Cambia el nivel de log directamente
Clerk('debug', {             // Configuración completa
  enable: true,
  level: 'log',
  group: true
});

Vía configuración

El modo debug también puede configurarse mediante la llamada estándar de configuración:

Clerk('config', 'debug', {
  enable: true,
  level: 'log',
  collect: true,
  group: true,
  collapsed: false
});

Hash en la URL

El modo debug puede activarse añadiendo un hash a la URL. Esto es útil para compartir enlaces con debug con colegas:

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

Cuando está activo a través del hash, la configuración también se guarda en sessionStorage bajo la clave __clerk_tmp_config.

Opciones de configuración #

Opción	Descripción	Tipo	Por defecto
`enable`	Activa o desactiva mensajes de depuración en la consola.	`bool`	`true`
`level`	Define el nivel de log. Valores aceptados: `log`, `warn`, o `error`.	`string`	`warn`
`collect`	Cuando es `true`, los mensajes de log se guardan en el almacenamiento del navegador. Si es `false`, se usa almacenamiento temporal.	`bool`	`true`
`group`	Agrupa los mensajes relacionados en la consola para fácil lectura.	`bool`	—
`collapsed`	Si es `true`, los mensajes agrupados están colapsados por defecto. Solo aplica si `group` está activado.	`bool`	—
`clear`	Elimina todos los mensajes de log guardados.	`bool`	—

Almacenamiento en sesión #

Cuando el modo debug está activo, la configuración se guarda en sessionStorage bajo la clave __clerk_debug. Esto garantiza que la configuración persista al navegar, sin afectar otras pestañas o permanecer después de la sesión.

Consent Management Platforms (CMPs) como Cookiebot pueden marcar __clerk_debug como un almacenamiento que requiere ser documentado. Es una clave funcional utilizada solo para fines de depuración de desarrolladores. No contiene datos personales ni información de rastreo.

Para detalles sobre la estructura de las respuestas de depuración de la API, consulta Response debugging.

UI Kit #

Clerk.js incluye un conjunto de herramientas UI para elementos importantes que pueden mejorar la experiencia del usuario. A menudo reducen el tiempo de desarrollo para integraciones personalizadas.

Buscador Instantáneo #

Una parte clave de una gran experiencia de búsqueda en e-commerce es obtener resultados de inmediato al empezar a escribir. Nuestro componente de Buscador Instantáneo hace que esta experiencia sea rápida y fácil de construir.

Cualquier contenido de Clerk.io puede, en teoría, ser hecho 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 búsqueda instantánea aquí.

Página de Búsqueda #

Una parte clave de una gran experiencia de búsqueda en e-commerce es obtener buenos resultados. Nuestra Search Page permite crear una página completa mostrando los mejores resultados posibles 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>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 Search Page aquí.

Página de Categoría #

Una página de categoría bien estructurada es clave para el éxito en eCommerce. Nuestra Category Page facilita la creación de una página mostrando los mejores resultados de 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 Category Page aquí.

Facetas #

Clerk.js incluye soporte integrado para navegación facetada dinámica en búsqueda y categorías. Cualquier atributo de producto que envíes puede ser usado como faceta.

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

Exit Intent #

El popup de exit intent reacciona cuando un visitante intenta salir de tu sitio moviendo el mouse cerca de la parte superior de la ventana del navegador. Se muestra un popup con productos interesantes, con la posibilidad de convertir ese visitante en cliente.

Cualquier bloque Element puede activarse ante 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 Exit Intent aquí.

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

Exclusión de productos #

Clerk.js tiene dos maneras de excluir productos, según si quieres excluir IDs específicos o evitar mostrar productos duplicados entre diferentes sliders.

Exclusión de IDs específicos #

Simplemente añade el atributo data-exclude al snippet. El contenido de data-exclude debe ser una lista de IDs de productos que no quieres mostrar, por ejemplo, los productos ya en el carrito o una lista de productos no permitidos.

<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 evitar duplicados. El valor debe ser un selector CSS de los demás snippets de los que quieres excluir duplicados.

En el ejemplo siguiente, .clerk-2 excluye cualquier producto que esté en .clerk-1, y .clerk-3 excluye cualquier producto presente 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 #

Cuando construyes flujos personalizados a menudo necesitarás reaccionar o modificar resultados de Clerk antes de renderizarlos. Aquí es útil Events.

Eventos te permiten crear listeners que ejecutan código antes, durante o después de que Clerk.js muestra sus resultados.

Un ejemplo común es cargar precios personalizados para un cliente logueado en B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk ha renderizado, lo que te permite obtener precios personalizados y agregarlos a los 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 los Eventos aquí.

SEO y Rendimiento #

Clerk.js potencia experiencias de compra personalizadas sin ralentizar tu sitio ni afectar el SEO. Usando renderizado en cliente y carga optimizada, equilibra velocidad, rendimiento y visibilidad en buscadores.

SEO y Velocidad #

Es un mito que funcionalidades en JavaScript como Clerk.js perjudiquen el rendimiento o el SEO. Las herramientas automáticas a menudo pasan por alto optimizaciones como caching, carga en paralelo y procesamiento en servidor.

Beneficios de la 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 son renderizados en cliente, lo que permite que tu HTML base sea cacheado, y los componentes dinámicos se inyectan luego de la carga.
Esto permite caching eficiente en servidor y carga sin bloqueos de los assets de Clerk.js.

Impacto en el rendimiento #

El tamaño reducido y carga asíncrona de Clerk.js implica que el impacto en los tiempos de carga es mínimo.
En la práctica, el mayor impacto suele venir de imágenes adicionales usadas en recomendaciones, no por el propio script. Para minimizarlo:
- Usa imágenes de tamaño y formato eficiente, como WebP.
- Redimensiona imágenes para adecuarlas a la visualización (ej. 400×400 px → máximo 420×420 px).
Para evitar saltos 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 SEO #

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

Enlazado y rastreo #

Clerk.js inyecta enlaces de recomendaciones de forma dinámica en cliente.
Estos enlaces pueden mejorar el enlazado interno conectando páginas relacionadas, si los buscadores pueden renderizarlos y seguirlos correctamente.
Ya que son inyectados en JavaScript, debes verificar cómo los crawlers renderizan e interpretan estos enlaces.
Los enlaces bien rastreados ayudan a descubrir e indexar más páginas.

Distribución de PageRank #

Cuando los buscadores pueden rastrearlos, los enlaces de Clerk.js mejoran la distribución de PageRank entre páginas clave.
Esto respalda una mayor visibilidad y ranking de páginas de productos y categorías.

Beneficios observados #

Una integración correcta de Clerk.js se correlaciona con una mejor estructura de enlazado interno, favoreciendo mejor visibilidad en buscadores.
Los paneles de Clerk.io brindan analíticas de influencia en pedidos, aumento de conversiones y contribuciones de ingresos desde Search, Recommendations, Email y Audience.

Mejores prácticas recomendadas #

Optimiza imágenes (formato WebP, resolución correcta).
Reserva espacio de layout para elementos dinámicos y evitar saltos de diseño.
Monitorea métricas reales en vez de depender solo de scores automáticos. Usa los paneles de Clerk para evaluar el impacto a través de 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

Descripción general #

Snippets #

Inyección #

Configuración #

IDs de visitante #

Contexto de página #

Idioma #

Funciones de diseño #

Formatters #

Globals #

Configuración #

Diseño #

Resultado #

Seguimiento de Email #

Cómo funciona la asociación #

Renderizado personalizado #

Depuración #

Métodos de activación #

Opciones de configuración #

Almacenamiento en sesión #

UI Kit #

Buscador Instantáneo #

Página de Búsqueda #

Página de Categoría #

Facetas #

Exit Intent #

Popup #

Exclusión de productos #

Exclusión de 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 y rastreo #

Distribución de PageRank #

Beneficios observados #

Mejores prácticas recomendadas #