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 super liviana.

Hay tres beneficios al usar Clerk.js:

Es robusta, ya que se carga de forma asíncrona. Esto significa que el resto de la página no depende de una respuesta de la API antes de cargar.
Suele ser más rápida, ya que tu servidor puede comenzar a renderizar la página en paralelo mientras Clerk.js realiza llamadas y renderiza los 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 del IP y 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 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 API para que ya sepa para qué Store 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 usa los atributos del fragmento para construir una llamada a la API mientras obtiene la clave API desde la configuración en el script de inicialización.

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

Los aspectos visuales se gestionan con el Design, que también es referenciado por el fragmento.

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

<span class="clerk"
     data-api="search/search"
     data-query="jedi"
     data-limit="20"
     data-template="#clerk-template">
</span>

<script type="text/x-template" id="clerk-template">
  <h1>Resultado de 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 pueden simplificarse 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>

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

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

Inyección #

La inyección es una función que te permite insertar fragmentos de contenido en tu sitio web sin tener que agregarlos manualmente. En su lugar, simplemente eliges un CSS Selector donde inyectar el fragmento, y Clerk.js lo agregará 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.

IDs de Visitante #

Por defecto, Clerk.js genera ID de visitantes anónimos, usados para rastrear las sesiones.

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

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

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

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

// Desactivar rastreo 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 rastreo para funciones de personalización como Disparadores de Email, segmentación de Audience, y contexto de Chat.

Clerk('context', {
  product: null,  // Establecer el ID de producto en páginas de producto, ej. 12345 o null
  category: null, // Establecer el ID de categoría en páginas de categoría, ej. 67 o null
  page: null      // Establecer identificador 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 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 admitidos están listados bajo los Idiomas compatibles.

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

product: El ID del producto que se está viendo en páginas de producto. Configura como null en páginas que no sean de producto.
category: El ID de la categoría que se está viendo en páginas de categoría. Configura como null en páginas que no sean de categoría.
page: Un identificador o cadena de tipo de página en otras páginas como inicio, carrito o checkout. Configura como null si no aplica.

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

Funciones de Diseño #

Clerk.js admite la adición de Formatters y Globals, los cuales pueden usarse para crear funcionalidad javascript personalizada para los alcances de tus diseños.

Formatters #

Se utilizan 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 conectado.

Globals #

Están pensados para usarse con datos de frontend a los que quieres acceder en los diseños. Ejemplos pueden ser la cantidad restante necesaria para obtener envío gratis, el nombre de un cliente registrado, 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 en emails incluso si aún no han realizado una compra.

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 inputs de email y envía automáticamente log/email cuando un visitante introduce una dirección de correo electrónico.

Si deseas registrar un email manualmente, también puedes añadir 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 cliente, llama a log/email cada vez que el email de un cliente conocido esté disponible en la sesión — tanto cuando inician sesión activamente como cuando vuelven al sitio ya autenticados.

El enfoque más sencillo es verificar en cada carga de página si hay un email disponible, y si lo hay, 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 email real desde tu plataforma. Solo muestra este script cuando haya un email disponible — omítelo completamente para visitantes.

Sin esto, Clerk.io solo puede vincular la sesión de un visitante a un correo electrónico cuando finaliza una compra. Registrar el email inmediatamente significa que la conexión se realiza de inmediato, lo que es requerido para disparar emails automáticos por comportamiento de navegación, mostrar recomendaciones personalizadas dentro de emails y aplicar campañas de Merchandising que segmenten Audiences específicos.

Cómo funciona la asociación #

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

Esto permite a Clerk identificar qué ha hecho ese visitante en su historial de sesión (por ejemplo, productos vistos, clics y búsquedas) y asociar ese comportamiento con la dirección de correo.

Con esa asociación, los mismos datos de comportamiento pueden usarse tanto para casos de uso de email (como emails automáticos y personalizados) como para la personalización onsite en recomendaciones para clientes conectados.

Renderizado personalizado #

Esto se usa principalmente con Single Page Apps (SPA), Progressive Web Apps (PWA) y otras aplicaciones que no usan cargas de página tradicionales.

Clerk.js renderiza cualquier elemento con la clase clerk, pero se pueden usar otras clases para personalizar el renderizado como selectores personalizados.

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

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

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

Depuración #

Clerk.js tiene un modo de depuración integrado que muestra información diagnóstica en la consola del navegador. Persiste su configuración en sessionStorage bajo la clave __clerk_debug, manteniendo el modo activo al navegar entre páginas en una misma sesión.

Por defecto, el modo de depuración está activado con level configurado en warn y collect en true.

Métodos de activación #

Hay tres maneras de activar el modo de depuración.

Atajo en la consola

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

Clerk('debug');              // Activar con valores predeterminados
Clerk('debug', true);        // Activar
Clerk('debug', false);       // Desactivar
Clerk('debug', 'on');        // Activar
Clerk('debug', 'off');       // Desactivar
Clerk('debug', 'warn');      // Establecer nivel de log directamente
Clerk('debug', {             // Pasar un objeto completo de configuración
  enable: true,
  level: 'log',
  group: true
});

Ruta config

El modo de depuración 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 de depuración puede activarse agregando un fragmento hash a la URL. Es útil para compartir enlaces de depuración con colegas:

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

Cuando se activa mediante la URL, la configuración también se guarda en sessionStorage bajo la clave __clerk_tmp_config.

Opciones de configuración #

Opción	Descripción	Tipo	Valor por defecto
`enable`	Activa o desactiva los mensajes en la consola del navegador.	`bool`	`true`
`level`	Establece el nivel de log. Los valores aceptados son `log`, `warn` o `error`.	`string`	`warn`
`collect`	Cuando es `true`, los mensajes de log se almacenan en el almacenamiento del navegador. Si es `false`, se usa almacenamiento temporal.	`bool`	`true`
`group`	Agrupa mensajes de log relacionados en la consola para facilitar la lectura.	`bool`	—
`collapsed`	Cuando es `true`, los mensajes agrupados de la consola aparecen colapsados por defecto. Solo aplica cuando `group` está activado.	`bool`	—
`clear`	Borra todos los mensajes almacenados.	`bool`	—

Almacenamiento en sesión #

Cuando el modo de depuración está activado, la configuración se guarda en sessionStorage bajo la clave __clerk_debug. Así los ajustes permanecen mientras los visitantes navegan entre páginas, sin afectar otras pestañas ni durar más allá de la sesión.

Sistemas de Gestión de Consentimiento (CMP) como Cookiebot pueden marcar __clerk_debug como un ítem de almacenamiento que requiere documentación. Es una clave funcional usada solo para propósitos 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, ver Depuración de respuestas.

UI Kit #

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

Búsqueda Instantánea #

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

Cualquier contenido de Clerk.io puede convertirse teóricamente en un componente de Búsqueda Instantánea, pero funciona mejor como un desplegable que muestra los resultados de búsqueda.

<span 
  class="clerk"
  
  data-api="search/predictive"
  data-limit="6"
  data-labels='["Instant Search"]'
      
  data-instant-search="INSERT_CSS_SELECTORS_HERE">
  
  <dl class="product-search-result-list">
    <dt>Productos que coinciden con <i>{{ query }}</i></dt>
    
    {% for product in products %}
      <dd class="product clerk-instant-search-key-selectable">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Comprar ahora</a>
      </dd>
    {% endfor %}
  </dl>
</span>

Lee más sobre la herramienta UI de Búsqueda Instantánea aquí.

Página de Búsqueda #

Una parte clave de una excelente experiencia de ecommerce es obtener buenos resultados de búsqueda. Nuestra Página de Búsqueda permite mostrar en una página completa los mejores resultados 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 Página de Búsqueda aquí.

Página de Categoría #

Una página de categoría bien estructurada es clave para el éxito en eCommerce. Nuestra Página de Categoría permite mostrar en una página completa 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 Página de Categoría aquí.

Facetas #

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

Aquí 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 UI Facetas aquí.

Exit Intent #

El popup de exit intent reacciona cuando un visitante intenta abandonar tu sitio colocando el cursor cerca de la parte superior de la ventana del navegador. Se muestra y presenta productos interesantes, convirtiendo posiblemente un visitante que se va en un comprador.

Cualquier bloque Element puede activarse ante una intención de salida añadiendo 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 UI Exit Intent aquí.

El UI Kit contiene una librería de popups para crear fácilmente popups sencillos pero amigables con cualquier contenido. Cualquier elemento HTML de tu sitio 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í.

Chat #

Clerk.js expone una interfaz JavaScript para controlar el widget de Chat y reaccionar a eventos de conversación. Es útil cuando quieres disparar el chat desde tu propia interfaz, enviarle datos contextuales a la IA sobre lo que hace el visitante o enlazar eventos de conversación con el resto de tu frontend.

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

Abrir Chat desde un botón personalizado #

Si quieres disparar Chat desde tu propio botón o elemento de UI en vez del lanzador por defecto, usa toggle:

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

También puedes usar open y close de forma independiente para controlar el estado explícitamente.

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 tu configuración global y hazlo visible de forma selectiva:

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

// 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 siempre que el contexto del visitante cambie — navegación, añadir a carrito, actualizar preferencias.

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

// Después de añadir un producto al 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 el contexto que necesites en cada página.

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

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

// Después de añadir al carrito — incita a la IA a sugerir productos cruzados
Clerk('chat', 'prompt_message', 'El usuario acaba de añadir un Lightsaber al carrito. Sugiere productos complementarios como accesorios o equipo de protección.');

// En la página de checkout — enfoca en completar la compra
Clerk('chat', 'prompt_message', 'El usuario está en la página de checkout. Ayúdale a completar su pedido y responde cualquier pregunta de último minuto.');

Transferencia a un agente humano #

Cuando un visitante necesita soporte humano, el evento onSupport se dispara con un resumen de la conversación. Úsalo para abrir el chat de tu helpdesk y pasar el contexto para que el agente ya tenga toda la información — sin que el visitante repita nada.

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

      // Ejemplo: abrir Intercom con contexto prellenado
      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 oculta Clerk Chat cuando se completa la transferencia
      Clerk('chat', 'disable');
    }
  }
});

El evento onSupport solo se dispara cuando Contact Support está configurado en ajustes de Chat y el visitante solicita explícitamente hablar con 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, registrar mensajes, sincronizar el estado o gestionar la transferencia a un humano.

Clerk('config', {
  key: 'your-public-api-key',
  chat: {
    onMessage: (e) => {
      // Se dispara en cada mensaje — role es 'user', 'ai' o 'results'
      console.log(e.message.role, e.message.text);
    },
    onOpen: (e) => {
      // Se dispara cuando se abre o cierra la ventana de Chat
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Se dispara cuando el visitante pide 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 Chat JS.

Excluir productos #

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

Excluir IDs específicos #

Simplemente añade el atributo data-exclude al fragmento. El contenido de data-exclude debe ser una lista de IDs de productos que no deseas mostrar, es decir, productos en el carrito del cliente o una lista de productos que no puede ver.

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

Evitar duplicados #

Esto se logra añadiendo el atributo data-exclude-from en el bloque Clerk donde deseas eliminar duplicados. El valor debe ser un selector CSS de otros fragmentos para evitar los duplicados.

En el ejemplo siguiente, .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 integraciones 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 escuchadores 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 integración B2B. Un evento puede ejecutarse justo después de que la API de Clerk haya terminado de renderizar, permitiéndote obtener precios personalizados y agregarlos 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. Mediante renderizado en cliente y carga optimizada, equilibra velocidad, desempeño y visibilidad en buscadores.

SEO y velocidad #

Es un mito que características JavaScript como Clerk.js dañen el rendimiento o el SEO. Las herramientas automáticas suelen ignorar optimizaciones como el caché, carga paralela y manejo en servidor.

Beneficios de integración de Clerk.js #

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

Impacto en el rendimiento #

La naturaleza ligera y asíncrona de Clerk.js generalmente resulta en un bajo impacto en los tiempos de carga.
El principal impacto de rendimiento en el mundo real suele deberse a imágenes adicionales en las recomendaciones, no al propio script. Para minimizarlo:
- Usa formatos de alta eficiencia y tamaño adecuado como WebP.
- Redimensiona las imágenes para que coincidan con las dimensiones mostradas (ej, 400×400 px → 420×420 px máx).
Para evitar desplazamientos 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 soporte tanto la experiencia del usuario como la visibilidad en buscadores.

Vinculación y rastreabilidad #

Clerk.js inyecta enlaces de recomendaciones dinámicamente en el 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, debes verificar cómo los rastreadores los renderizan e interpretan.
Si son rastreados correctamente, los enlaces mejoran la rastreabilidad y los motores pueden descubrir e indexar más páginas.

Distribución de PageRank #

Cuando los motores pueden rastrearlos, los enlaces de Clerk.js pueden ayudar a distribuir el link equity (PageRank) entre las páginas clave.
Esto favorece la visibilidad y el ranking de productos y categorías.

Beneficios observados #

Una integración correcta de Clerk.js puede correlacionarse con estructuras de enlaces internos más fuertes, que favorecen una mayor visibilidad en los resultados de búsqueda.
Los paneles de Clerk.io ofrecen analíticas sobre influencia en pedidos, aumento de conversión y contribución a los ingresos de Search, Recommendations, Email y Audience.

Buenas prácticas recomendadas #

Optimiza imágenes (formato WebP, resolución correcta).
Reserva espacio de layout para elementos dinámicos y evitar desplazamientos.
Monitorea métricas reales en lugar de depender solo de puntuaciones automáticas. 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.

Clerk.js

Descripción general #

Fragmentos #

Inyección #

Configuración #

IDs de Visitante #

Contexto de Página #

Idioma #

Funciones de Diseño #

Formatters #

Globals #

Configuración #

Diseño #

Salida #

Seguimiento de Email #

Clientes registrados #

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 #

Búsqueda Instantánea #

Página de Búsqueda #

Página de Categoría #

Facetas #

Exit Intent #

Popup #

Chat #

Abrir Chat desde un botón personalizado #

Mostrar Chat solo en páginas específicas #

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

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

Transferencia a un agente humano #

Reaccionar a eventos de Chat #

Excluir productos #

Excluir IDs específicos #

Evitar duplicados #

Eventos #

SEO y rendimiento #

SEO y velocidad #

Beneficios de integración de Clerk.js #

Impacto en el rendimiento #

Consideraciones SEO #

Vinculación y rastreabilidad #

Distribución de PageRank #

Beneficios observados #

Buenas prácticas recomendadas #