Cualquier (webshop)

Clerk.js

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

Descripción general #

Clerk.js es una biblioteca de JavaScript que simplifica la integración de nuestra API con el frontend. Con tan solo 37.7 kb, 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 cargar.
  • A menudo es más rápida, ya que tu servidor puede comenzar a renderizar la página en paralelo mientras Clerk.js realiza 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 y el useragent del visitante, combinado con una sal única de la 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 -->

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 API para que ya sepa para qué Tienda está realizando llamadas a la API.

Fragmentos #

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

Luego utiliza los atributos del fragmento para construir una llamada a la API mientras obtiene 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>

La apariencia visual se gestiona por el Diseño, el cual también es referenciado por el fragmento.

Clerk.js utiliza diseños Liquid para renderizar HTML con los datos devueltos por la API. Estos son formateados 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 búsqueda 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 se pueden simplificar para incluir solo una referencia a un bloque Element, utilizando la sintaxis data-template="@element-block-id":

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

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

Tus fragmentos 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 #

La inyección es una función que te permite insertar fragmentos de contenido en tu sitio web sin tener que agregarlos manualmente. En su lugar, simplemente eliges un Selector CSS para 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 varias configuraciones que cambian cómo funciona.

Para configurar Clerk.js en my.clerk.io, abre tu Tienda y ve a Developers > Clerk.js Config. Ajusta la configuración y haz clic en Save.

Estas configuraciones se aplican automáticamente cuando Clerk.js carga. No sobrescriben valores ya establecidos en tu fragmento de seguimiento o en la consola del navegador. Los cambios pueden tardar hasta 10 minutos en aplicarse.

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

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

Contexto de página #

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

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

El contexto también puede proporcionar los IDs usados por los bloques de recomendaciones. Consulta Ajustes de contexto de Element para saber cómo usarlo con Inyección.

Idioma #

Configura Clerk.js con el idioma escrito del sitio web. Esto se usa para que Clerk.io maneje correctamente las reglas gramaticales en Search y para obtener las traducciones correctas cuando utilice feeds multi-idioma.

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

Los valores aceptados están listados en Idiomas soportados.

Reemplaza los valores de ejemplo con la lógica de tu plataforma para obtener los IDs dinámicamente. Cada valor debe establecerse en función del tipo de página en la que se encuentra el visitante:

  • product: El ID del producto que se está visualizando en las páginas de producto. Establécelo como null en páginas que no son de producto.
  • category: El ID de la categoría que se está visualizando en las páginas de categoría. Establécelo como null en páginas que no son de categoría.
  • page: Un identificador o cadena de tipo de página en otras páginas como inicio, carrito o checkout. Establécelo como null si no es aplicable.

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 que sean relevantes.

Funciones de diseño #

Clerk.js permite agregar Formatters y Globals, los cuales pueden ser usados para crear funcionalidades javascript personalizadas para tus diseños.

Formatters #

Estos se usan para influir o cambiar atributos. Por ejemplo, puede que solo quieras mostrar los primeros 40 caracteres de una descripción, o que necesites calcular un descuento específico basado en el tipo de cliente que ha iniciado sesión.

Globals #

Estos se utilizan con datos del frontend a los que deseas acceder en los diseños. Puede ser, por ejemplo, el monto restante para lograr el envío gratis, el nombre del cliente que ha iniciado sesión, un símbolo de moneda, o una tasa de conversión.

A continuación, 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 recopilar emails automáticamente en la sesión del cliente para personalizar recomendaciones de email incluso si aún no han realizado una compra.

Para activar la recopilación automática de emails en my.clerk.io, abre tu tienda, ve a Developers > Clerk.js Config, habilita Collect Emails, y haz clic en Save.

Alternativamente, habilita collect_email en tu configuración Clerk.js en el código:

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

Con esto habilitado, Clerk.js monitoriza los inputs de email y automáticamente envía log/email cuando un visitante introduce una dirección de correo electrónico.

Esto identifica al visitante; no lo suscribe a marketing. Consulta Configuración de Email para la gestión de suscripciones.

Si deseas registrar un email manualmente, también puedes agregar un fragmento como este:

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

Clientes registrados #

Si tu tienda online tiene cuentas de clientes, llama a log/email siempre que una dirección de email de un cliente conocido esté disponible en la sesión, tanto cuando inicien sesión activamente como cuando regresen a la web ya logueados.

El enfoque más sencillo es comprobar en cada carga de la página si hay un email disponible, y si es así, hacer la llamada. Para evitar llamadas innecesarias a la API, almacena una bandera en la sesión del navegador para que solo se dispare una vez por sesión:

<script type="text/javascript">
  if (!sessionStorage.getItem('clerk_email_logged')) {
    Clerk('call', 'log/email', {
      email: 'CUSTOMER_EMAIL'
    });
    sessionStorage.setItem('clerk_email_logged', '1');
  }
</script>

Reemplaza CUSTOMER_EMAIL con la dirección de correo real de tu plataforma. Solo renderiza este script cuando la dirección esté disponible — omítelo completamente para invitados.

Sin esto, Clerk.io solo puede vincular la sesión de un visitante con una dirección de email cuando completan una compra. Registrarlo siempre que esté disponible permite que la conexión se haga inmediatamente, lo cual es necesario para activar emails automáticos basados en el comportamiento de navegación, mostrar recomendaciones personalizadas dentro de emails y aplicar campañas de Merchandising que apunten a segmentos específicos de Audience.

Cómo funciona la asociación #

Cuando se registra un email, Clerk envía tanto el ID de visitante 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 el historial de su sesión (por ejemplo, productos vistos, clics y búsquedas) y asocie ese comportamiento con la dirección de email.

Con esa asociación en vigor, los mismos datos de comportamiento pueden ser usados tanto para correos electrónicos personalizados (como emails automáticos y personalizados) como para la personalización onsite en recomendaciones para clientes registrados.

Recargas de contexto #

Las recargas de contexto mantienen las recomendaciones relevantes a medida que el comprador navega en una SPA (aplicación de una sola página) o una tienda “headless” sin recargar la página completa. Por ejemplo, un bloque de “Popular en esta categoría” puede refrescarse cuando el comprador cambia de categoría.

Esto está habilitado por defecto para los bloques cuyos IDs provienen del contexto de Clerk.js (id_source: 'context'). Cuando un valor de contexto cambia, Clerk.js vuelve a renderizar los bloques ya inicializados que usan esa clave, con el valor actualizado.

Actualizar contexto #

Llama al setter público de contexto cuando cambie el valor relevante. Por ejemplo, después de navegar a la categoría 276:

Clerk('context', 'category', '276');

Reemplaza 276 con el ID de categoría de tu tienda. Puedes establecer el contexto antes o después de que un bloque se inicialice. Establecer el mismo valor otra vez no hace nada ni dispara otra recarga.

Las claves observadas son:

ClaveComportamiento
productActualiza los bloques derivados del producto actual. También suministra el tipo plural de ID products.
categoryActualiza los bloques derivados de la categoría actual.
pageActualiza los bloques derivados del contexto de la página actual.
emailRellena o actualiza bloques cuando el contexto email está disponible o cambia.

Comparación con observer #

Las recargas de contexto funcionan incluso con la observación del DOM desactivada. Refrescan bloques ya en la página cuando un valor cambia, sin requerir un cambio en el HTML.

La observación del DOM detecta markup añadido para que Clerk.js pueda inicializar bloques agregados recientemente e intentar inyecciones cuando aparece su objetivo. Se activa por separado. Las recargas de contexto no usan MutationObserver, temporizadores ni listeners del DOM.

Evento de contexto #

Utiliza el evento context para reaccionar a cambios en tu propio frontend. Se dispara por cada cambio real de contexto, incluso cuando las recargas automáticas están deshabilitadas. El evento pertenece al contexto, no a un bloque en particular.

Clerk('on', 'context', ({ key, value, previous, context }) => {
  // Actualiza tu propia UI aquí si es necesario.
});

Deshabilitar recargas #

Si tu tienda gestiona estas actualizaciones de UI por sí misma, deshabilita las recargas automáticas de contexto con:

Clerk('config', 'context_watch', false);

El evento context sigue disponible cuando las recargas automáticas están deshabilitadas.

En aplicaciones de una sola página, popstate y hashchange ejecutan nuevamente el paso compartido de contenido e inyección. Las inyecciones dirigidas por URL pueden crearse cuando cambian las condiciones coincidentes y los bloques derivados de contexto se recargan cuando sus valores cambian.

Actualiza el contexto de Clerk.js a medida que el comprador navega para que los valores coincidan con la vista actual. Consulta la guía SPA para la inicialización y renderizado manual.

Límites #

Los bloques cuyos IDs provienen de elementos de la página, y los popups, no se recargan por cambios de contexto.

Durante la inyección, un bloque que le falte un valor de contexto requerido se omite hasta el siguiente ciclo de inyección. El email es la excepción: los bloques de email pueden crearse sin un email y rellenarse cuando esté disponible.

La observación del DOM puede provocar el ciclo de inyección que crea un bloque omitido. Este fallback es independiente de la recarga de un bloque que ya ha sido renderizado.

Cada cambio de clave crea una petición API adicional. Evita actualizar el contexto en bucles cerrados o en cada evento de ruta a menos que los cambios de valor sean intencionados.

Observación del DOM #

Activa la observación del DOM cuando tu tienda añade contenido Clerk.io después de que la página haya cargado. Clerk.js observa los cambios en la estructura de la página (el DOM) para poder captar el contenido al aparecer.

Puedes habilitar el mismo comportamiento mediante SPA Auto Detect Changes en my.clerk.io o añadiendo observe_dom: true a tu configuración de Clerk.js.

Ejemplo de carrito lateral #

Imagina que tu tienda solo crea el carrito lateral cuando un visitante añade un producto. El carrito incluye un fragmento de recomendación de Clerk.io, por lo que ese fragmento se añade a la página al abrir el carrito.

Con el enfoque basado en temporizador, Clerk.js comprueba los cambios una vez por segundo. El fragmento de recomendación puede esperar hasta la siguiente comprobación antes de que Clerk.js lo recoja.

Con observe_dom activado, agregar el carrito lateral dispara una comprobación. Clerk.js puede captar el fragmento antes y empezar a mostrar las recomendaciones, reduciendo la espera tras la aparición del carrito.

Otros ejemplos #

El mismo comportamiento ayuda en otros entornos donde aparece contenido sin recarga total de la página:

  • Popup de añadir al carrito: La tienda crea un popup con recomendaciones Clerk.io tras añadir un producto. Clerk.js detecta el contenido al crearse el popup.
  • Sección lazy-loaded: La tienda añade un bloque Clerk.io más abajo mientras el visitante navega. Clerk.js lo detecta al añadirse.
  • Aplicación de una sola página: Una app React o Vue añade contenido Clerk.io al navegar a otra vista. Clerk.js detecta el contenido añadido sin esperar a una recarga total de la página.

La observación del DOM también se aplica a bloques de contenido, formularios de registro de email y búsqueda en vivo.

Activar observación #

Elige cualquiera de estos métodos para activar la observación del DOM:

  • Backend: En my.clerk.io, abre tu tienda y ve a Settings > Features. Habilita SPA Auto Detect Changes.
  • Código: Añade observe_dom: true a tu configuración de Clerk.js existente, como se muestra a continuación.

Ambas opciones activan la misma función, por lo que solo necesitas una de ellas.

Clerk('config', {
  key: 'INSERT_PUBLIC_API_KEY',
  observe_dom: true
});

Mantén la clave API pública de tu tienda y cualquier otra opción ya presente en tu configuración.

Aún necesitas añadir el fragmento de Clerk.io adecuado y configurar su Element y Design. Activar la observación ayuda a Clerk.js a detectar contenido añadido después; no agrega ubicaciones de recomendación a tu tienda.

Para renderizado manual y selectores personalizados, consulta Renderizado personalizado.

Uso de recursos #

Clerk.js agrupa ráfagas rápidas de cambios en una sola pasada y limita los ciclos completos a uno cada 500 ms. El observer no hace nada mientras la página está inactiva y no introduce llamadas API ni tráfico de red adicionales.

Esta configuración es opcional. Las tiendas que no la activan mantienen el comportamiento existente.

Renderizado personalizado #

Esto se utiliza principalmente con Aplicaciones de Página Única (SPA), Aplicaciones Web Progresivas (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 debe mostrarse.

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

Este comportamiento continúa hasta que se haga un refresco completo de página.

Depuración #

Clerk.js incluye un modo de depuración incorporado que registra información de diagnóstico en la consola del navegador. Persiste su configuración en sessionStorage bajo la clave __clerk_debug, manteniendo el modo debug activo en las distintas páginas durante la misma sesión de navegador.

Por defecto, el modo debug está habilitado con level en warn y collect en true.

Métodos de activación #

Hay tres formas de activar el modo debug.

Atajo desde la consola

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

Clerk('debug');              // Habilita con valores por defecto
Clerk('debug', true);        // Habilita
Clerk('debug', false);       // Deshabilita
Clerk('debug', 'on');        // Habilita
Clerk('debug', 'off');       // Deshabilita
Clerk('debug', 'warn');      // Establece el nivel de log directamente
Clerk('debug', {             // Pasa un objeto de configuración completo
  enable: true,
  level: 'log',
  group: true
});

Ruta de configuración

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

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

Hash de la URL

El modo debug puede activarse añadiendo un fragmento hash a la URL. Esto es útil para compartir enlaces de depuración con compañeros:

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

Al activarse vía hash en la URL, la configuración también se guarda en sessionStorage bajo la clave __clerk_tmp_config.

Opciones de configuración #

OpciónDescripciónTipoPor defecto
enableActiva o desactiva mensajes de depuración en la consolabooltrue
levelEstablece el nivel de log. Valores aceptados: log, warn o error.stringwarn
collectCuando es true, almacena mensajes de log en el storage del navegador. Si es false, se usa storage temporal.booltrue
groupAgrupa mensajes de log relacionados en la consola para facilitar la lectura.bool—
collapsedCuando es true, los grupos en consola se muestran colapsados por defecto. Activo solo si group está habilitado.bool—
clearElimina todos los mensajes de log almacenados.bool—

Almacenamiento en sesión #

Cuando se activa el modo debug, la configuración se guarda en sessionStorage bajo la clave __clerk_debug. Esto asegura que la configuración de depuración persiste mientras los visitantes navegan entre páginas, sin afectar otras pestañas del navegador ni durar más allá de la sesión.

Plataformas de gestión de consentimiento (CMPs) como Cookiebot pueden marcar __clerk_debug como un ítem de almacenamiento que debe ser documentado. Es una clave funcional usada 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 Depuración de respuesta.

UI Kit #

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

Búsqueda Instantánea #

Una parte clave de una excelente experiencia de búsqueda e-commerce es recibir resultados instantáneamente a medida que escribes. Nuestro componente UI de Búsqueda Instantánea hace que esto sea rápido y fácil de montar.

Cualquier contenido de Clerk.io puede, en teoría, convertirse 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 de UI de Búsqueda Instantánea aquí.

Página de búsqueda #

Una parte fundamental de una gran experiencia de búsqueda es obtener buenos resultados. Nuestra Página de Búsqueda 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 de UI de Página de Búsqueda aquí.

Página de categoría #

Una página de categoría bien estructurada es clave para el éxito de un negocio eCommerce. Nuestra Página de Categoría permite crear rápidamente una página 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 }}">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 de UI de Página de Categoría aquí.

Facetas #

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 puede usarse como faceta.

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

Lee más sobre la herramienta de UI de Facetas 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. Aparece mostrando productos interesantes y puede convertir un visitante que abandona en comprador.

Cualquier bloque Element se puede mostrar cuando se detecta el intento de salida agregando el atributo data-exit-intent="true" al fragmento.

<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 de Exit Intent aquí.

El UI Kit contiene una librería de popup sencilla para crear popups fáciles de usar con cualquier contenido. Cualquier elemento HTML en tu sitio 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 de UI de Popup aquí.

Chat #

Clerk.js expone una interfaz JavaScript para controlar el widget de Chat y reaccionar a eventos de conversación. Esto es útil si quieres activar el chat desde tu propia UI, pasarle datos contextuales al AI sobre lo que está haciendo el visitante, o unir eventos al resto del frontend.

La referencia completa de métodos y eventos está disponible en la documentación de Chat JS.

Abrir Chat desde un botón personalizado #

Si quieres activar Chat desde tu propio botón o elemento UI en lugar del launcher por defecto, usa toggle:

<button onclick="Clerk('chat', 'toggle')">
  ¿Necesitas ayuda?
</button>

También puedes utilizar open y close independientemente para controlar el estado de manera explícita.

Mostrar Chat solo en páginas específicas #

Por defecto, Chat es visible en todo el sitio. Para mostrarlo solo en ciertas páginas, desactívalo en la configuración global y actívalo de forma puntual:

// En tu configuración global de Clerk.js — oculta Chat en todas partes
Clerk('config', { key: 'your-public-api-key' });
Clerk('chat', 'disable');

// Luego, en las páginas donde quieras mostrarlo
Clerk('chat', 'enable');

Pasar contexto de carrito y página a la IA #

El método metadata envía contexto estructurado a Chat para que la IA pueda dar respuestas más relevantes. Llama al método siempre que cambie el contexto del visitante: navegación, añadir al carrito o actualizaciones de preferencias.

// En la página de producto
Clerk('chat', 'metadata', {
  current_page: {
    page_type: 'product',
    page_id: '12345'
  }
});

// Después de que un visitante añade un producto a su carrito
Clerk('chat', 'metadata', {
  cart: {
    items: [
      { id: 101, name: 'Lightsaber', price: 99.95 },
      { id: 204, name: 'Force Gloves', price: 29.95 }
    ],
    total: 129.90
  }
});

La estructura del payload es flexible — incluye cualquier contexto que sea útil para las conversaciones que ocurran en esa página.

Ajustar el comportamiento de IA según la actividad del visitante #

El método prompt_message envía una instrucción a nivel de sistema a la IA. El cliente nunca la ve, pero cambia cómo responde la IA en la conversación actual.

// Tras añadir al carrito — orientar la IA al cross-sell
Clerk('chat', 'prompt_message', 'El usuario acaba de añadir un Lightsaber a su carrito. Sugiere productos complementarios como accesorios o equipo de protección.');

// En la página de checkout — enfocar en terminar la compra
Clerk('chat', 'prompt_message', 'El usuario está en la página de checkout. Ayúdale a completar el pedido y responde cualquier pregunta de última hora.');

Transferencia a un agente humano #

Cuando un visitante necesita soporte humano, el evento onSupport se dispara con un resumen de la conversación. Utilízalo para abrir el chat de tu helpdesk y pasar el contexto, de modo que el agente esté al tanto — el visitante no tendrá que repetir lo que ya ha dicho.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onSupport: (e) => {
      // e.summary contiene un resumen en texto plano de la conversación hasta ahora
      const summary = e.summary || 'No hay resumen de conversación disponible.';

      // Ejemplo: abrir Intercom y pre-poblar contexto
      if (window.Intercom) {

Intercom('showNewMessage', 'Continuando desde AI Chat:\n\n' + summary);
      }

      // Ejemplo: abrir Zendesk con contexto prellenado
      if (window.zE) {
        zE('messenger', 'open');
        zE('messenger:set', 'conversationFields', [
          { id: 'clerk_chat_summary', value: summary }
        ]);
      }

      // Opcionalmente ocultar Clerk Chat una vez que la transferencia esté completa
      Clerk('chat', 'disable');
    }
  }
});

El evento onSupport solo se activa cuando Contact Support está configurado en la configuración de Chat y el visitante solicita explícitamente un humano.

Reaccionar a eventos de Chat #

Usa hooks de eventos para integrar el comportamiento de Chat con el resto de tu frontend — por ejemplo, registrando mensajes, sincronizando estados o transfiriendo a un agente humano.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onMessage: (e) => {
      // Se activa en cada mensaje — role es 'user', 'ai', o 'results'
      console.log(e.message.role, e.message.text);
    },
    onOpen: (e) => {
      // Se activa cuando la ventana de Chat se abre o cierra
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Se activa cuando el visitante solicita un agente humano
      // e contiene un resumen de la conversación
      openLiveChatWithSummary(e);
    }
  }
});

También puedes registrar hooks de eventos dinámicamente después de la configuración inicial:

Clerk('chat', 'on', 'message', function(e) {
  console.log('Nuevo mensaje:', e.message.text);
});

Lee más en la documentación de Chat JS.

Exclusión de productos #

Clerk.js tiene 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 agrega el atributo data-exclude al snippet. El contenido de data-exclude debe ser una lista de los IDs de producto que no deseas mostrar, es decir, los productos en el carrito de compras del cliente o una lista de productos que no pueden ver.

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

Evitar duplicados #

Esto se hace agregando el atributo data-exclude-from en el Clerk Block donde quieras eliminar el duplicado. El valor del atributo debe ser un selector CSS para el/los otro(s) snippet(s) del que prevenir duplicados.

En el ejemplo a continuación, .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 #

Cuando se crean configuraciones más personalizadas, a menudo necesitarás reaccionar o modificar los resultados de Clerk antes de mostrarlos. 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 renderice sus resultados.

Un ejemplo común es cargar precios personalizados para un cliente registrado en una configuración B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk haya terminado 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 impulsa experiencias de compra personalizadas sin ralentizar tu sitio ni perjudicar el SEO. Al usar renderizado del lado del cliente y una carga optimizada, equilibra velocidad, rendimiento y visibilidad en búsquedas.

SEO y velocidad #

Es un mito que características en JavaScript como Clerk.js perjudican el rendimiento o el SEO. Las herramientas automáticas a menudo pasan por alto optimizaciones como el caché, la carga en paralelo y el manejo del lado del servidor.

Beneficios de la integración de Clerk.js #

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

Impacto en el rendimiento #

  • La naturaleza ligera y asíncrona de Clerk.js generalmente resulta en un impacto mínimo en los tiempos de carga de la página.
  • El impacto real en el rendimiento a menudo proviene de imágenes adicionales mostradas en recomendaciones, no del script en sí. Para minimizar el impacto:
    • Usa formatos adecuados y eficientes como WebP.
    • Redimensiona las imágenes para igualar las dimensiones de la pantalla (ejemplo: 400×400 px → máximo 420×420 px).
  • Para evitar saltos de diseño (CLS), reserva espacio para el contenido inyectado de Clerk.

Ejemplo:

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

Consideraciones para SEO #

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

Enlazado y rastreabilidad #

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

Distribución de PageRank #

  • Cuando los motores de búsqueda pueden rastrearlos, los enlaces de Clerk.js pueden ayudar a distribuir la autoridad (PageRank) entre páginas clave.
  • Esto respalda una mejor visibilidad y posicionamiento de páginas de producto y categorías.

Beneficios observados #

  • Una integración correcta de Clerk.js puede correlacionarse con estructuras de enlazado interno más sólidas, lo que puede ayudar a mejorar la visibilidad en los resultados de búsqueda.
  • Los paneles de Clerk.io proporcionan análisis sobre la influencia en pedidos, mejoras en la conversión y contribuciones de ingresos provenientes de Search, Recommendations, Email y Audience.

Prácticas recomendadas #

  1. Optimiza imágenes (formato WebP, resolución correcta).
  2. Reserva espacio de diseño para elementos dinámicos y evitar saltos de diseño.
  3. Monitorea métricas reales en vez de depender solo de puntajes automáticos. Usa los paneles 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.