Cualquier (webshop)

Clerk.js

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

Descripción general #

Clerk.js es una librería de JavaScript que simplifica la integración de nuestra API con el frontend. Con solo 37.7kb, es una solución super ligera.

Hay tres ventajas al usar Clerk.js:

  • Es robusto, ya que se carga de forma asíncrona. Esto significa que el resto de la página no depende de una respuesta de la API antes de cargarse.
  • Muchas veces es 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 maneja automáticamente para cualquier resultado mostrado por Clerk. Esto no requiere cookies, ya que generamos un valor hash de la IP del visitante y useragent, combinado con una sal personalizada única de la tienda que cambia 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 librería desde nuestro CDN y te permite acceder a sus funcionalidades mediante el objeto Clerk, además de configurar Clerk.js con la clave API para que ya sepa para qué Store está realizando llamadas a la API.

Snippets #

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

Luego utiliza los atributos del snippet para construir una llamada a la API, obteniendo 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 visualización se gestiona por el Design, que también está referenciado en el snippet.

Clerk.js utiliza diseños Liquid para renderizar HTML con los datos devueltos por la API. Estos se formatean como scripts y se referencian por su ID en data-template en tu snippet.

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

<script type="text/x-template" id="clerk-template">
  <h1>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 }}">Comprar ahora</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 incluir solo 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 luego se gestionan con el Editor de Diseños o con código Liquid HTML de forma sencilla desde my.clerk.io.

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

Inyección #

La inyección es una función que permite insertar snippets de contenido en tu sitio web sin tener que agregarlos manualmente. Solo debes elegir un Selector CSS para inyectar el snippet, y Clerk.js lo agregará 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 modifican su funcionamiento.

IDs de visitante #

Por defecto, Clerk.js genera IDs de visitantes anónimos, que se utilizan para rastrear las sesiones.

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

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 la sesión 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 el visitante está viendo. Esto se utiliza para enriquecer los datos de seguimiento para características de personalización como Email Triggers, segmentación de Audience y contexto de Chat.

Clerk('context', {
  product: null,  // Establecer el ID de producto en páginas de producto, por ejemplo 12345 o null
  category: null, // Establecer el ID de categoría en páginas de categoría, por ejemplo 67 o null
  page: null      // Establecer un ID o tipo de página en otras páginas, como 'homepage' o null
});

Idioma #

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

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

Los valores aceptados se pueden consultar en Idiomas soportados.

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

  • product: El ID del producto que se visualiza en páginas de producto. Establecer en null en páginas que no sean de producto.
  • category: El ID de la categoría que se visualiza en páginas de categoría. Establecer en null en páginas que no sean de categoría.
  • page: Un identificador de página o tipo de página para otras páginas como la página de inicio, carrito o checkout. Establecer en null si no corresponde.

Si tu plataforma no dispone de un ID específico para un tipo de página, deja el valor en null. Solo asigna valores para los tipos de página relevantes.

Funciones de diseño #

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

Formatters #

Estos se usan para influir o cambiar atributos. Por ejemplo, puedes desear mostrar solo los primeros 40 caracteres de una descripción, o necesitas calcular un porcentaje de descuento específico dependiendo del tipo de cliente conectado.

Globals #

Estos están pensados para usarse con datos del frontend a los que quieras acceder en los diseños. Por ejemplo: la cantidad restante para alcanzar el envío gratis, el nombre de un cliente registrado, un símbolo de moneda o una tasa de conversión.

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

Habilita 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 habilitado, Clerk.js monitoriza los inputs de email y envía automáticamente log/email cuando un visitante escribe una dirección de correo.

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 registrados #

Si tu tienda online tiene cuentas de clientes, llama a log/email cada vez que el email conocido de un cliente esté disponible en la sesión — tanto cuando inician sesión como cuando regresan ya conectados.

El enfoque más sencillo es comprobar en cada carga de página si hay un email disponible, y si lo hay, realizar la llamada. Para evitar llamadas innecesarias a la API, guarda una bandera en la sesión del navegador para que solo se ejecute 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 por la dirección de correo real proporcionada por tu plataforma. Solo renderiza este script cuando realmente exista un email — saltálo completamente para visitantes sin registro.

Sin esto, Clerk.io solo puede asociar la sesión del visitante con una dirección de correo cuando se completa una compra. Al registrarlo en cuanto el email está disponible, la conexión se realiza de inmediato, lo que es necesario para activar envíos automáticos basados en comportamiento, mostrar recomendaciones personalizadas en emails y aplicar campañas de Merchandising dirigidas 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 el correo electrónico a la API para que puedan conectarse.

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 al correo.

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

Observación del DOM #

Habilita la observación del DOM cuando tu tienda online agregue contenido de Clerk.io después de la carga de la página. Clerk.js observa los cambios en la estructura de la página (DOM) para detectar el contenido en cuanto aparezca.

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

Ejemplo de Side Cart #

Imagina que tu tienda solo crea su side cart cuando el visitante añade un producto. El carrito incluye un snippet de recomendación Clerk.io, por lo que ese snippet se añade a la página cuando se abre el carrito.

Con el enfoque basado en temporizador, Clerk.js revisa los cambios una vez por segundo. El snippet de recomendación puede esperar hasta la siguiente revisión antes de que Clerk.js lo detecte.

Con observe_dom habilitado, añadir el side cart dispara una revisión inmediata. Clerk.js puede detectar el snippet más rápido y empezar a renderizar las recomendaciones, reduciendo la espera después de que aparezca el carrito.

Otros ejemplos #

El mismo comportamiento ayuda en otras configuraciones donde el contenido aparece sin recargar la página completa:

  • Popup de añadir al carrito: La tienda genera un popup con recomendaciones Clerk.io después de añadir un producto. Clerk.js detecta el contenido añadido cuando se crea el popup.
  • Sección cargada por lazy-load: La tienda añade un bloque Clerk.io más abajo a medida que el visitante hace scroll. Clerk.js lo detecta cuando se añade.
  • App de una sola página: Una app React o Vue añade contenido Clerk.io cuando el visitante navega a otra vista. Clerk.js detecta el contenido agregado sin esperar a una recarga completa.

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

Activar observación #

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

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

Ambas opciones habilitan la misma función, solo necesitas usar una.

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

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

Igualmente tienes que añadir el snippet de Clerk.io correspondiente y configurar su Element y Design. Habilitar la observación ayuda a Clerk.js a detectar el contenido añadido más tarde; no añade ubicaciones de recomendación automáticamente a tu tienda online.

Para renderizado manual y selectores personalizados, consulta Renderizado personalizado.

Uso de recursos #

Clerk.js agrupa ráfagas rápidas de cambios de página en una sola pasada y limita las pasadas completas a una vez cada 500 ms. El observador no hace trabajo mientras la página está inactiva y no añade llamadas adicionales a la API ni tráfico de red.

La configuración es voluntaria. Las Stores que no la habilitan mantienen el comportamiento anterior.

Renderizado personalizado #

Se usa principalmente con Single Page Apps (SPA), Progressive Web Apps (PWA) y otras aplicaciones que no siguen el modelo tradicional de carga de página.

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

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

Al añadir auto_init_custom_selectors: true a la configuración, Clerk.js inicializa automáticamente cualquier elemento con selector personalizado conforme el DOM cambia, siempre que hayan sido ya renderizados al menos una vez con Clerk("content", "SELECTOR").

Este comportamiento continúa hasta que se recarga completamente la página.

Depuración #

Clerk.js tiene un modo de depuración integrado que registra información de diagnóstico en la consola del navegador. Mantiene su configuración en sessionStorage bajo la clave __clerk_debug, conservando el modo de depuración activo durante la navegación de la sesión del navegador.

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

Métodos de activación #

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

Acceso directo en consola

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

Clerk('debug');              // Habilita con valores predeterminados
Clerk('debug', true);        // Habilita
Clerk('debug', false);       // Deshabilita
Clerk('debug', 'on');        // Habilita
Clerk('debug', 'off');       // Deshabilita
Clerk('debug', 'warn');      // Ajusta el nivel de logs 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 mediante la llamada de configuración estándar:

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

Hash en la URL

El modo debug puede activarse añadiendo un 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 a través del hash de URL, la configuración también se guarda en sessionStorage bajo la clave __clerk_tmp_config.

Opciones de configuración #

OpciónDescripciónTipoPor defecto
enableHabilita o deshabilita mensajes de depuración en la consola del navegador.booltrue
levelAjusta el nivel de logs. Los valores aceptados son log, warn o error.stringwarn
collectSi es true, los mensajes de log se almacenan en el storage del navegador. Si es false, se usa un almacenamiento temporal.booltrue
groupAgrupa mensajes de log relacionados en la consola para facilitar la lectura.bool—
collapsedSi es true, los mensajes de consola agrupados están colapsados por defecto. Solo aplica si group está habilitado.bool—
clearElimina todos los mensajes de log almacenados.bool—

Almacenamiento de sesión #

Cuando el modo de depuración se activa, la configuración se guarda en sessionStorage bajo la clave __clerk_debug. Esto asegura que las configuraciones persistan mientras el visitante navega entre páginas, sin afectar otras pestañas ni durar más allá de la sesión.

Plataformas de Gestión de Consentimiento (CMPs) como Cookiebot pueden marcar __clerk_debug como un elemento de almacenamiento que requiere documentación. Es una clave funcional usada únicamente para propósitos de depuración para desarrolladores. No contiene datos personales ni información de seguimiento.

Para más detalles sobre la estructura de las respuestas de depuración de la API, consulta Depuración de respuestas.

UI Kit #

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

Una parte clave de una buena experiencia de Search en un e-commerce es obtener resultados al momento de empezar a escribir. Nuestro componente de Instant Search facilita construir y satisfacer esa experiencia de usuario.

Cualquier contenido de Clerk.io puede convertirse en un componente de Instant Search, 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 Instant Search UI aquí.

Search Page #

Una parte clave de una buena experiencia de Search es obtener resultados relevantes. Nuestra Search Page permite construir fácilmente una página completa con las mejores coincidencias para cualquier consulta.

La Search Page te permite crear una página completa mostrando los mejores resultados para cualquier búsqueda.

<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 Search Page UI aquí.

Category Page #

Una página de categoría bien estructurada es clave para el éxito en eCommerce. Nuestra Category Page permite construir fácilmente 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 }}">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 Category Page UI aquí.

Facets #

Clerk.js viene con soporte integrado para navegación dinámica con facetas tanto en Search como en categorías. Cualquier atributo de producto enviado puede usarse como faceta.

Aquí tienes un ejemplo básico de uso:

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

<span 
  class="clerk" 
      
  data-template="@search-page" 
  data-query="shoes"
  
  data-facets-target="#clerk-search-filters" 
  data-facets-attributes='["price","categories","brand"]'
  data-facets-titles='{"price": "PRICE-TRANSLATION", "categories": "CATEGORIES-TRANSLATION", "brand": "BRAND-TRANSLATION"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="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 un visitante intenta abandonar tu sitio moviendo el mouse cerca de la parte superior de la ventana del navegador. Se muestra y presenta productos interesantes, pudiendo convertir un visitante que se va en un cliente.

Cualquier bloque Element puede ser disparado al detectar intención de salida agregando el atributo data-exit-intent="true" al snippet.

<span
  class="clerk"
  
  data-api="recommendations/visitor/complementary"
  data-limit="20"
  data-labels='["Exit Intent / Popup"]'
  
  data-exit-intent="true">
</span>

Lee más sobre la herramienta Exit Intent UI aquí.

El UI Kit incluye una sencilla librería para crear popups fáciles y amigables con cualquier contenido. Cualquier elemento HTML en 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 Popup UI aquí.

Chat #

Clerk.js expone una interfaz de JavaScript para controlar el widget de Chat y reaccionar a eventos de conversación. Esto es útil si quieres abrir Chat desde tu propia UI, pasar información contextual de lo que está haciendo el visitante al AI, o engancharte a los eventos de la conversación desde el resto de tu frontend.

Puedes consultar la referencia completa de métodos y eventos en la Chat JS docs.

Abrir Chat desde un botón personalizado #

Si quieres abrir Chat desde tu propio botón o elemento de UI en vez del lanzador estándar, usa toggle:

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

También puedes usar open y close de manera independiente para controlar el estado de forma 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 tu configuración global y actívalo de manera selectiva:

// En tu configuración 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 quieres que sea visible
Clerk('chat', 'enable');

Pasando contexto del carrito y la página al AI #

El método metadata envía contexto estructurado a Chat para que la AI pueda dar respuestas más relevantes. Llama a este método cada vez que cambie el contexto del visitante — navegación de página, añadir productos al carrito, actualizar preferencias.

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

// Después de que un visitante agrega 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 todo el contexto que sea útil para las conversaciones en esa página.

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

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

// Tras añadir al carrito — sugiere ventas cruzadas
Clerk('chat', 'prompt_message', 'El usuario acaba de añadir un Lightsaber a su carrito. Sugiere productos complementarios como accesorios o equipos de protección.');

// En la página de checkout — enfoca en concretar 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 última hora.');

Redirigir a un agente humano #

Cuando un visitante necesita soporte humano, el evento onSupport se activa con un resumen de la conversación. Úsalo para abrir el chat de tu helpdesk y pasar el contexto para que el agente esté al corriente de inmediato — sin necesidad de que el visitante repita información.

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 y pre-llenar el contexto
      if (window.Intercom) {
        Intercom('showNewMessage', 'Continuando desde AI Chat:\n\n' + summary);
      }

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

      // Opcionalmente, ocultar Chat de Clerk una vez realizada la transferencia
      Clerk('chat', 'disable');
    }
  }
});

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

Reaccionar a eventos de Chat #

Utiliza hooks de eventos para integrar el comportamiento de Chat con el resto de tu frontend — por ejemplo, registrar mensajes, sincronizar estado o derivar a un agente.

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 al abrir o cerrar la ventana de Chat
      analytics.track('Chat toggled', { open: e.open });
    },
    onSupport: (e) => {
      // Se dispara cuando el visitante solicita un agente humano
      // e contiene un resumen de la conversación
      openLiveChatWithSummary(e);
    }
  }
});

También puedes registrar hooks de eventos de forma dinámica tras 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.

Excluir productos #

Clerk.js ofrece dos formas 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 snippet. El contenido de data-exclude debe ser una lista de IDs de los productos que no quieres mostrar (por ejemplo los productos en el carrito del cliente o una lista de productos restringidos).

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

Evitar duplicados #

Esto se hace añadiendo el atributo data-exclude-from en el bloque de Clerk donde quieras eliminar el duplicado. El valor del atributo debe ser un selector CSS para el/los snippet(s) del que evitar duplicados.

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

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

Eventos #

Al construir configuraciones más personalizadas, a menudo necesitarás reaccionar o modificar los resultados de Clerk antes de renderizarlos. Para esto sirven los Events.

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

Un caso común es cargar precios personalizados para un cliente en un entorno B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk termine de renderizar, permitiendo que recuperes precios personalizados para el cliente y los añadas a los productos:

var customer_id = INSERT_CUSTOMER_ID;
Clerk("on", "rendered", function(content, data){
  for (i = 0; i < data.product_data.length; i++) {
      var product = data.product_data[i];
        var custom_price = FETCH_PRICE_FROM_SERVER(product.id,customer_id);
        let price_container = document.querySelector(`[data-clerk-product-id='${product.id}'] .clerk-price`);
        price_container.innerText = custom_price;
    }
})

Lee más sobre Events aquí.

SEO y rendimiento #

Clerk.js impulsa experiencias de compra personalizadas sin ralentizar tu sitio ni perjudicar el SEO. Usando renderizado del lado del cliente y una carga optimizada, equilibra velocidad, rendimiento y visibilidad de búsqueda.

SEO y velocidad #

Es un error común pensar que características de JavaScript como Clerk.js afectan negativamente el rendimiento o el SEO. Las herramientas automatizadas a menudo pasan por alto optimizaciones como el almacenamiento en caché, la carga paralela y el procesamiento en servidor.

Beneficios de la integración de Clerk.js #

  • El script de Clerk.js (≈ 37 - 38 KB) se carga de forma asíncrona, permitiendo que tu sitio se renderice mientras Clerk se inicializa.
  • Los elementos de Clerk se renderizan en el cliente, lo que significa que tu HTML base sigue siendo cacheable y los componentes dinámicos solo se inyectan después de la carga.
  • Esto permite un almacenamiento eficiente 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 sobre los tiempos de carga de página.
  • El impacto real muchas veces proviene de imágenes adicionales mostradas en recommendations, no del propio script. Para minimizar el impacto:
    • Utiliza formatos de alta eficiencia y tamaño adecuado como WebP.
    • Redimensiona las imágenes al tamaño de visualización (ej., 400×400 px → 420×420 px máximo).
  • Para evitar cambios de maquetación (CLS), reserva espacio para el contenido inyectado de Clerk.

Por ejemplo:

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

Consideraciones sobre SEO #

Entender cómo interactúa Clerk.js con los buscadores te ayuda a garantizar que tu implementación brinde tanto buena experiencia de usuario como visibilidad en búsqueda.

Enlazado y rastreabilidad #

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

Distribución de PageRank #

  • Cuando los buscadores pueden rastrearlos, los enlaces de Clerk.js pueden ayudar a distribuir link equity (PageRank) entre páginas clave.
  • Esto apoya una mejor visibilidad y posicionamiento de páginas de productos y categorías.

Beneficios observados #

  • Una integración correcta de Clerk.js puede correlacionar con estructuras internas de enlazado más sólidas, lo que podría favorecer una mejor visibilidad en los resultados de búsqueda.
  • Los dashboards de Clerk.io ofrecen analíticas sobre influencia en pedidos, incrementos en la conversión y contribuciones en ingresos de las funciones de Search, Recommendations, Email y Audience.

Prácticas recomendadas #

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

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