Clerk.js

Visión general #

Clerk.js es una biblioteca de JavaScript que simplifica la integración de nuestra API con el frontend. Con solo 37.7kb, es una solución súper ligera.

Hay tres beneficios en el uso de 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 empezar 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 hasheado de la IP y useragent del visitante, combinado con una clave única de la tienda que rota cada 30 días.

Clerk.js se carga con un script de inicialización añadido al header del sitio web:

<!-- Start of Clerk.io E-commerce Personalisation tool - www.clerk.io -->
<script type="text/javascript">
  (function(w,d){
    var e=d.createElement('script');e.type='text/javascript';e.async=true;
    e.src='https://cdn.clerk.io/clerk.js';
    var s=d.getElementsByTagName('script')[0];s.parentNode.insertBefore(e,s);
    w.__clerk_q=w.__clerk_q||[];w.Clerk=w.Clerk||function(){ w.__clerk_q.push(arguments) };
  })(window,document);

  Clerk('config', {
    key: 'insert_api_key'
  });
</script>
<!-- End of Clerk.io E-commerce Personalisation tool - www.clerk.io -->

Carga la biblioteca desde nuestro CDN y te permite acceder a sus funcionalidades a través del objeto Clerk, y configura Clerk.js con la clave de API para que ya sepa para qué Store está haciendo llamadas a la API.

Snippets #

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

Luego usa los atributos del snippet para construir una llamada a la API mientras obtiene la clave de 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>

La visualización está gestionada por el Design, que también se referencia en el snippet.

Clerk.js utiliza Liquid designs para renderizar HTML con los datos que devuelve la API. Estos están formateados como scripts, referenciados por su ID en data-template en tu snippet.

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

<script type="text/x-template" id="clerk-template">
  <h1>Resultado de Search para {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Buy Now</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Cargar más resultados</a>
</script>

Los snippets también se pueden simplificar para solo incluir 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 Designs se gestionan después con el Editor de Designs o con código Liquid HTML de forma intuitiva desde my.clerk.io.

Tus snippets solo tendrán que 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 funcionalidad que te permite insertar snippets de contenido en tu sitio web sin tener que hacerlo de forma manual. Simplemente eliges un Selector CSS para inyectar el snippet y Clerk.js lo añadirá automáticamente al cargar la página.

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

Configuración #

Clerk.js permite una variedad de configuraciones que cambian cómo funciona.

IDs de visitante #

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

Si los clientes aceptan cookies, se puede configurar Clerk.js para colocar una cookie persistente con el ID de visitante, permitiendo el seguimiento 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 completamente el seguimiento de sesiones estableciendo visitor en null.

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

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

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

Contexto de página #

Configura Clerk.js con el contexto de la página que un visitante está viendo actualmente. Esto se usa para enriquecer los datos de seguimiento para funcionalidades de personalización como disparadores de Email Triggers, 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 el ID o tipo de página para otras páginas, ej. 'homepage' o null
});

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

Idioma #

Configura Clerk.js con el idioma escrito del sitio web. Esto permite que Clerk.io maneje correctamente las reglas gramaticales en Search y obtenga las traducciones correctas cuando utilizas feeds multilingües.

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

Los valores aceptados se encuentran listados en Supported languages.

Sustituye los valores de ejemplo por la lógica de tu plataforma para obtener los IDs dinámicamente. Cada valor debe establecerse según el tipo de página donde se encuentre el visitante:

• product: El ID del producto visto en páginas de producto. Establecer a null en páginas que no sean de producto.
• category: El ID de la categoría vista en páginas de categoría. Establecer a null en páginas que no sean de categoría.
• page: Un identificador o cadena de tipo de página para otras páginas como inicio, carrito o checkout. Establecer a 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 asigna valores para los tipos de página relevantes.

Funciones de diseño #

Clerk.js soporta la incorporación de Formatters y Globals, que pueden usarse para crear funcionalidad JavaScript personalizada para tus ámbitos de diseño.

Formatters #

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

Globals #

Se usan con datos de frontend a los que deseas acceder en los designs. Por ejemplo, el importe restante para obtener envío gratuito, el nombre del usuario logueado, un símbolo de moneda o un tipo de cambio.

A continuación 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 por email incluso si aún no ha 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 detecta campos de email y envía automáticamente log/email cuando un visitante introduce una dirección de email.

Si quieres registrar un email manualmente, también puedes añadir un snippet como este:

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

Clientes logueados #

Si tu tienda online tiene cuentas de cliente, llama a log/email siempre que una dirección de email conocida esté disponible en la sesión, tanto cuando el cliente inicia sesión activamente como cuando regresa ya autenticado.

La forma más sencilla es comprobar en cada carga de página si hay un email disponible, y si es así, ejecutar la llamada. Para evitar llamadas innecesarias a la API, guarda una bandera en la sesión del navegador para que solo se lance 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>

Sustituye CUSTOMER_EMAIL por la dirección de email real de tu plataforma. Solo muestra este script cuando realmente haya una dirección de email disponible; omítelo para invitados.

Sin esto, Clerk.io solo puede vincular la sesión de un visitante a una dirección de email cuando completa una compra. Registrar el email tan pronto como esté disponible permite que la conexión se realice inmediatamente, lo que 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 de Audience concretos.

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 ser conectados.

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

Una vez establecida la asociación, los mismos datos de comportamiento pueden usarse tanto para emails (como desencadenados y personalizados) como para personalización onsite en recomendaciones para clientes identificados.

Recargas de contexto #

Las recargas de contexto mantienen las recomendaciones relevantes mientras un comprador navega en una aplicación de página única o un escaparate headless sin recarga completa. Por ejemplo, un bloque “Popular en esta categoría” puede refrescarse cuando el usuario navega a otra categoría.

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

Actualizar contexto #

Llama al método público para establecer contexto cuando cambie su valor relevante. Por ejemplo, tras navegar a la categoría 276:

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

Sustituye 276 por el ID de categoría de tu tienda. Puedes establecer el contexto antes o después de inicializar un bloque. Si asignas el mismo valor de nuevo, no sucede nada ni se recarga otro bloque.

Las claves monitorizadas son:

Comparación con Observer #

Las recargas de contexto funcionan incluso con observación del DOM desactivada. Actualizan los bloques ya presentes en la página al cambiar un valor, sin requerir cambios en el HTML de la página.

La observación del DOM detecta el marcado añadido para que Clerk.js pueda iniciar los bloques agregados y reintentar inyecciones cuyo destino acaba de aparecer. Está habilitada por separado. Las recargas de contexto no usan MutationObserver, timers ni escuchas del DOM.

Evento de contexto #

Utiliza el evento context para reaccionar a cambios en tu frontend. Se dispara para cada cambio real de contexto, incluso con recargas automáticas desactivadas. El evento pertenece al contexto, no a un bloque individual.

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

Desactivar recargas #

Si tu frontend gestiona estas actualizaciones de UI, desactiva las recargas automáticas de contexto con:

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

El evento context sigue estando disponible aunque las recargas automáticas estén desactivadas.

Navegación #

En aplicaciones de página única, popstate y hashchange ejecutan el proceso de contenido e inyección compartido nuevamente. Se pueden crear inyecciones orientadas por URL cuando cambian sus condiciones de coincidencia y los bloques derivados del contexto se recargan al cambiar sus valores.

Actualiza el contexto de Clerk.js conforme el cliente navega para mantener los valores alineados con la vista actual. Consulta la guía para SPA para inicialización y renderizado manual.

Límites #

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

Durante la inyección, un bloque que carece de un valor de contexto requerido queda pendiente hasta el siguiente pase de inyección. La excepción es el email: los bloques de email pueden crearse sin un email y poblarse cuando este esté disponible.

La observación del DOM puede provocar el pase de inyección que crea un bloque previo pendiente. Este mecanismo es independiente de la recarga de un bloque ya renderizado.

Cada clave modificada genera una solicitud adicional a la API. Evita actualizar el contexto en bucles cerrados o en cada evento de ruta salvo cambios de valor realmente intencionados.

Observación del DOM #

Activa la observación del DOM cuando tu tienda online agrega contenido de Clerk.io tras la carga inicial. Clerk.js vigila cambios en la estructura de la página, llamada DOM, para detectar el contenido cuando aparece.

Puedes habilitar este comportamiento desde 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 snippet de recomendaciones de Clerk.io, por lo que ese snippet se añade a la página al abrir el carrito.

Con el enfoque basado en temporizador, Clerk.js verifica cambios una vez por segundo. El snippet de recomendación puede esperar al siguiente chequeo antes de que Clerk.js lo detecte.

Con observe_dom activo, añadir el carrito lateral dispara la revisión. Clerk.js puede detectar el snippet antes y empezar a mostrar las recomendaciones más rápido tras aparecer el carrito.

Otros ejemplos #

El mismo comportamiento ayuda en otros entornos donde aparece contenido sin una recarga completa:

• Popup de añadir al carrito: El e-commerce crea un popup con recomendaciones de Clerk.io después de añadir un producto. Clerk.js detecta el contenido cuando se crea el popup.
• Sección lazy-loaded: Se añade un bloque Clerk.io más abajo conforme el usuario se desplaza. Clerk.js lo detecta al añadirse.
• SPA: Una app React o Vue añade contenido Clerk.io cuando el usuario navega entre vistas. Clerk.js lo detecta sin esperar recarga completa.

La observación del DOM también aplica a bloques de contenido, formularios de suscripción de email y el buscador en vivo.

Cómo activar la observación #

Escoge una de estas formas para habilitar la observación del DOM:

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

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

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

Mantén la clave pública de API de tu Store y otras opciones ya existentes en tu configuración.

Sigue necesitando añadir el snippet de Clerk.io pertinente y configurar su Elemento y Design. Habilitar la observación ayuda a Clerk.js a detectar el contenido añadido después; no añade ubicaciones de recomendaciones automáticamente.

Para renderizado manual y selectores personalizados, consulta Custom Rendering.

Uso de recursos #

Clerk.js agrupa ráfagas rápidas de cambios de la página en un solo pase y limita pases completos a cada 500 ms. El observer no trabaja si la página está inactiva y no introduce solicitudes adicionales a la red.

El ajuste es voluntario. Las tiendas que no lo activen mantienen el comportamiento tradicional.

Renderizado personalizado #

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

Clerk.js renderiza cualquier elemento con la clase clerk, pero pueden usarse otras clases como selectores personalizados.

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

Si añades auto_init_custom_selectors: true a la config, Clerk.js inicializa automáticamente elementos con selectores personalizados a medida que el DOM cambia, siempre y cuando ya hayan sido renderizados con Clerk("content", "SELECTOR") una vez.

Este comportamiento se mantiene hasta que se recarga por completo la página.

Depuración #

Clerk.js tiene un modo debug integrado que registra información diagnóstica en la consola del navegador. Persiste su configuración en sessionStorage bajo la clave __clerk_debug, manteniendo debug activo durante la navegación en la misma sesión.

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.

Atajo de consola

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

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

Config path

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

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

URL hash

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

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

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

Opciones de configuración #

Almacenamiento de sesión #

Al activar el modo debug, la configuración se guarda en sessionStorage bajo la clave __clerk_debug. Así se mantienen los ajustes de depuración entre páginas, sin afectar otras pestañas ni durar más allá de la sesión.

Las plataformas de consentimiento (CMP), como Cookiebot, pueden marcar __clerk_debug como un elemento de almacenamiento a documentar. Es una clave funcional solo para depuración de desarrolladores. No contiene datos personales ni de seguimiento.

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

UI Kit #

Clerk.js incluye un set de herramientas UI para elementos importantes que pueden usarse para mejorar la experiencia de usuario. Suelen ahorrar tiempo de desarrollo en integraciones personalizadas.

Instant Search #

Una parte clave de una gran experiencia de Search en E-commerce es obtener resultados inmediatamente al empezar a escribir. El componente Instant Search de UI facilita y agiliza esta experiencia.

Cualquier contenido de Clerk.io teóricamente puede convertirse en un componente Instant Search, pero funciona mejor como un desplegable mostrando resultados.

<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 }}">Buy Now</a>
      </dd>
    {% endfor %}
  </dl>
</span>

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

Search Page #

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

La Search Page te permite crear una página completa mostrando las mejores coincidencias para cualquier consulta.

<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 }}">Buy Now</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 Search Page UI aquí.

Category Page #

Una página de categoría bien estructurada es clave para un negocio E-commerce exitoso. Nuestra Category Page hace que esta experiencia sea rápida y fácil de construir. Te permite crear una página completa mostrando los mejores resultados para cualquier categoría.

<span 
  class="clerk"
  
  data-api="recommendations/category/popular"
  data-limit="40"
  data-labels='["Category Page Grid"]'
  data-category="INSERT_CATEGORY_ID"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">
  
  <div class="product-category-result-list">
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostrar más resultados
    		</div>
    {% endif %}
  </div>
</span>

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

Facets #

Clerk.js incluye soporte integrado para navegación dinámica facetada tanto para Search como para categorías. Cualquier atributo de producto que envíes puede utilizarse como facet.

Aquí tienes un ejemplo de uso básico:

<div id="clerk-search-filters"></div>

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "PRICE-TRANSLATION", "categories": "CATEGORIES-TRANSLATION", "brand": "BRAND-TRANSLATION"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="Ver más"
  data-facets-searchbox-text="Buscar "
  data-facets-design="133995">
</span>

Lee más sobre la herramienta Facets UI aquí.

Exit Intent #

El popup de exit intent reacciona cuando el visitante intenta salir del sitio colocando su mouse cerca de la parte superior de la ventana del navegador, mostrando productos interesantes y convirtiendo a un visitante que se va en un cliente potencial.

Cualquier bloque de Element puede activarse con la intención de salir 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 UI aquí.

Popup #

El UI Kit incluye una librería de popup sencilla para crear popups amigables fácilmente 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">¡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 Popup UI aquí.

Chat #

Clerk.js expone una interfaz JavaScript para controlar el widget Chat y reaccionar a eventos de conversación. Esto es útil si quieres lanzar el chat desde tu propia UI, pasar contexto de IA sobre lo que hace el visitante o conectarte a eventos de conversación desde el 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 lanzar Chat desde tu propio botón o elemento de UI en lugar del launcher por defecto, usa toggle:

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

También puedes usar open y close independientemente para controlar el estado manualmente.

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 config global y actívalo donde lo necesites:

// En tu config global de Clerk.js — oculta Chat en todo el sitio
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 dé respuestas más relevantes. Llámalo cada vez que cambie el contexto del visitante: navegación, agregar al carrito, actualizar preferencias, etc.

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

// Tras 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 más útil en cada página.

Ajustar el comportamiento de la IA según lo que hace el usuario #

El método prompt_message envía una instrucción de sistema a la IA. El cliente nunca la ve, pero modifica las respuestas de la IA en la conversación actual.

// Tras añadir al carrito — indica a la IA que sugiera cross-sell
Clerk('chat', 'prompt_message', 'El usuario acaba de añadir un Lightsaber al carrito. Sugiere productos complementarios como accesorios o equipamiento protector.');

// En la página de checkout — enfoca en completar la compra
Clerk('chat', 'prompt_message', 'El usuario está en la página de checkout. Ayuda a completar su pedido y resolver preguntas de última hora.');

Escalar a un agente humano #

Cuando un visitante necesita soporte humano, se dispara el evento onSupport con un resumen de la conversación. Úsalo para abrir tu chat de helpdesk y pasar el contexto, de modo que el agente tenga todo el historial y el usuario no deba repetir nada.

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

      // Ejemplo: abrir Intercom con el contexto
      if (window.Intercom) {
        Intercom('showNewMessage', 'Continuando desde AI Chat:\n\n' + summary);
      }

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

      // Opcionalmente ocultar Chat Clerk tras el traspaso
      Clerk('chat', 'disable');
    }
  }
});

El evento onSupport solo se dispara si Contact Support está configurado en Chat y el visitante solicita explícitamente un humano.

Reaccionar a eventos de Chat #

Usa hooks de evento para integrar el comportamiento de Chat con el resto de tu frontend—por ejemplo, registrar mensajes, sincronizar estado o escalar a un agente humano.

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.

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 los IDs de productos 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 realiza añadiendo el atributo data-exclude-from en el bloque Clerk donde desees eliminar el duplicado. El valor del atributo debe ser un selector CSS para el/los otro(s) snippet(s) del que quieras evitar duplicados.

En el siguiente ejemplo, .clerk-2 excluye cualquier producto que esté en .clerk-1, y .clerk-3 excluye cualquier producto que esté en .clerk-1 o .clerk-2.

<span class="clerk clerk-1"
  data-template="@clerk-banner-1">
</span>
 
<span class="clerk clerk-2"
  data-exclude-from=".clerk-1"
  data-template="@clerk-banner-2">
</span>
 
<span class="clerk clerk-3"
  data-exclude-from=".clerk-1,.clerk-2"
  data-template="@clerk-banner-3">
</span>

Eventos #

Cuando desarrolles configuraciones más personalizadas, a menudo necesitarás reaccionar o modificar los resultados de Clerk antes de renderizarlos. Aquí es donde los Eventos son útiles.

Los eventos te permiten configurar listeners que ejecutan código en momentos específicos antes, durante o después de que Clerk.js renderice sus resultados.

Un ejemplo común es cargar precios personalizados para un cliente logueado en una configuración B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk termine de renderizar, permitiéndote obtener precios personalizados para un cliente y 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 dañar el SEO. Al utilizar renderizado en el lado del cliente y carga optimizada, equilibra velocidad, rendimiento y visibilidad en los motores de búsqueda.

SEO y Velocidad #

Es un error común pensar que características JavaScript como Clerk.js perjudican el rendimiento o el SEO. Las herramientas automatizadas suelen pasar por alto optimizaciones como caché, carga en paralelo y manejo en el servidor.

Beneficios de la integración de Clerk.js #

• El script de Clerk.js (≈ 37 - 38 KB) se carga de forma asíncrona, permitiendo que tu sitio se renderice mientras Clerk se inicializa.
• Los elementos 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 eficiente almacenamiento en caché del lado del servidor y una carga no bloqueante de los assets de Clerk.js.

Impacto en el rendimiento #

• La naturaleza ligera y asíncrona de Clerk.js normalmente resulta en un impacto pequeño en los tiempos de carga de página.
• En la práctica, la principal ralentización proviene de imágenes adicionales mostradas en recomendaciones, no del propio script. Para minimizar el impacto:
  • Utiliza formatos de alta eficiencia y tamaño adecuado como WebP.
  • Redimensiona las imágenes para que coincidan con las dimensiones de visualización (p.ej., 400×400 px → 420×420 px máx.).
• Para evitar saltos de diseño (CLS), reserva espacio para el contenido inyectado por Clerk.

Por ejemplo:

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

Consideraciones SEO #

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

Enlazado e indexabilidad #

• Clerk.js inyecta enlaces de recomendaciones 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 mediante JavaScript, deberías verificar cómo los crawlers de los motores de búsqueda los renderizan e interpretan.
• Los enlaces correctamente rastreados pueden mejorar la rastreabilidad y permitir que los motores de búsqueda descubran e indexen 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 ranking de páginas de producto y categoría.

Beneficios observados #

• Una integración correcta de Clerk.js puede correlacionarse con estructuras de enlaces internos más sólidas, lo que puede ayudar a mejorar la visibilidad en los resultados de búsqueda.
• Los paneles de Clerk.io proporcionan analíticas sobre la influencia en pedidos, incrementos de conversión y contribuciones de ingresos a partir de las características Search, Recommendations, Email y Audience.

Mejores prácticas recomendadas #

1. Optimiza las imágenes (formato WebP, resolución adecuada).
2. Reserva espacio de diseño para los elementos dinámicos y evitar saltos de diseño.
3. Monitorea métricas reales en lugar de depender solo de puntuaciones automatizadas. Utiliza los dashboards de Clerk para evaluar el impacto en todos los canales.