Cualquier (webshop)

Clerk.js

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

Descripción general #

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

Hay tres beneficios al usar Clerk.js:

Es robusto, ya que se carga de forma asíncrona. Esto significa que el resto de la página no depende de la respuesta de una API antes de cargar.
Suele ser más rápido, ya que tu servidor puede comenzar a renderizar la página en paralelo mientras Clerk.js realiza llamadas y muestra resultados.
El seguimiento de visitantes y clics se gestiona automáticamente para cualquier resultado mostrado por Clerk. Esto no requiere cookies, ya que generamos un valor hash de la IP y el useragent del visitante, combinado con un salt único de la tienda que rota cada 30 días.

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

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

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

Carga la biblioteca desde nuestro CDN y te permite acceder a sus funcionalidades a través del objeto Clerk, además de configurar Clerk.js con la clave API para que ya sepa para qué Store está realizando las 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 utiliza los atributos del snippet para construir una llamada a la API obteniendo 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>

El diseño visual es gestionado por el Design, que también es referenciado por el snippet.

Clerk.js utiliza diseños Liquid para renderizar HTML con los datos devueltos por 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>Search result for {{ query }}.</h1>
  {% for product in products %}
    <div class="product">
      <h2>{{ product.name }}</h2>
      <img src="{{ product.image }}" />
      <a href="{{ product.url }}">Buy Now</a>
    </div>
  {% endfor %}

  <a href="javascript:Clerk('content', '#{{ content.id }}', 'more', 20);">Load More Results</a>
</script>

Los snippets también pueden simplificarse 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 se gestionan con el Editor de Diseño o con código Liquid HTML de una manera amigable desde my.clerk.io.

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

Inyección #

La inyección es una función que te permite insertar snippets de contenido en tu sitio web sin tener que agregarlos manualmente. En su lugar, simplemente eliges un Selector CSS donde inyectar el snippet y Clerk.js lo añadirá automáticamente al cargar la página.

Lee más sobre Injection aquí.

Configuración #

Clerk.js permite una variedad de configuraciones que cambian su funcionamiento.

IDs de Visitante #

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

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

Si prefieres gestionar manualmente los IDs de sesión, puedes configurar el parámetro visitor que Clerk usa en las llamadas a la API. Alternativamente, puedes desactivar el rastreo de sesión completamente estableciendo visitor en null.

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

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

// Deshabilitar 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 en ese momento. Esto se utiliza para enriquecer los datos de seguimiento en funciones de personalización como Email Triggers, Audience segmentación y Chat context.

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

Idioma #

Configura Clerk.js con el idioma escrito del sitio web. Esto es usado por Clerk.io para manejar correctamente las reglas gramaticales en Search y para recuperar las traducciones correctas cuando usas feeds multilenguaje.

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

Los valores aceptados se encuentran en Idiomas soportados.

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

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

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

Funciones de Diseño #

Clerk.js permite agregar Formatters y Globals, que pueden utilizarse para crear funcionalidades personalizadas en JavaScript para los diseños.

Formatters #

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

Globals #

Están pensados para usarse con datos del frontend a los que necesitas acceder en tus diseños. Esto puede incluir el monto restante para obtener envío gratis, el nombre de un cliente con sesión iniciada, 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 recoger emails automáticamente en la sesión del cliente para personalizar recomendaciones de email, incluso si aún no han realizado una compra.

Esto se configura en Clerk.js con collect_email: true como se muestra aquí:

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

Con esto, Clerk.js monitoreará todos los campos de entrada en el sitio web y lo registra con log/email cuando un visitante escribe una dirección de email en alguno de ellos:

https://api.clerk.io/v2/log/email?payload={"email":"test@test.com","key":"insert_api_key","visitor":"auto"}

Renderizado Personalizado #

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

Clerk.js muestra todos los elementos 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 selector personalizado a medida que el DOM muta, siempre y cuando ya hayan sido renderizados al menos una vez con Clerk("content", "SELECTOR").

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

Depuración #

Clerk.js incluye un modo de depuración que registra información de diagnóstico en la consola del navegador. Su configuración persiste en sessionStorage bajo la clave __clerk_debug, manteniendo el modo de depuración activo entre navegaciones dentro de la misma sesión de navegador.

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

Métodos de activación #

Existen tres formas de activar el modo de depuración.

Abreviatura en consola

La manera más sencilla 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 objeto de configuración completo
  enable: true,
  level: 'log',
  group: true
});

Ruta de configuración

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 ser activado 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 en 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`	Habilita o deshabilita los mensajes de debug en la consola del navegador.	`bool`	`true`
`level`	Establece el nivel de log. Valores aceptados: `log`, `warn`, o `error`.	`string`	`warn`
`collect`	Cuando es `true`, los mensajes de log se almacenan en el almacenamiento del navegador. Con `false`, se usa almacenamiento temporal.	`bool`	`true`
`group`	Agrupa mensajes de log relacionados en la consola para facilitar la lectura.	`bool`	—
`collapsed`	Si es `true`, los mensajes agrupados están colapsados por defecto. Solo aplica si `group` está habilitado.	`bool`	—
`clear`	Borra todos los mensajes de log 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. Esto asegura que los ajustes de depuración persistan mientras el usuario navega entre páginas, sin afectar otras pestañas o durar más allá de la sesión.

Plataformas de Consentimiento (CMPs) como Cookiebot pueden marcar __clerk_debug como un elemento 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, consulta Depuración de respuestas.

UI Kit #

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

Instant Search #

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

Cualquier contenido de Clerk.io puede convertirse en un componente de Instant Search, pero funciona mejor como un desplegable que muestra resultados de búsqueda.

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

Lee más sobre el UI de Instant Search aquí.

Search Page #

Una parte clave de una excelente experiencia de búsqueda en e-commerce es obtener buenos resultados de búsqueda. Nuestra Search Page permite construir fácilmente 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>Products matching <i>{{ query }}</i></div>
    
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

Lee más sobre el UI de Search Page aquí.

Category Page #

Una página de categoría bien estructurada es clave para un negocio de eCommerce exitoso. Nuestra Category Page hace que esta experiencia sea rápida y fácil de construir. Permite crear una página completa mostrando los mejores resultados posibles 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);">
          		Show More Results
    		</div>
    {% endif %}
  </div>
</span>

Lee más sobre el UI de Category Page aquí.

Clerk.js cuenta con 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 utilizado como facet.

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="View More"
  data-facets-searchbox-text="Search for "
  data-facets-design="133995">
</span>

Lee más sobre el UI de Facets aquí.

Exit Intent #

El popup de exit intent reacciona cuando un visitante intenta abandonar tu sitio moviendo el cursor cerca de la parte superior de la ventana del navegador. Se muestra y presenta productos interesantes, lo que puede convertir a un visitante que se va en un cliente comprador.

Cualquier bloque Element puede ser activado cuando un visitante muestra intención de salir 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 el UI de Exit Intent aquí.

El UI Kit contiene una biblioteca de popups simple para crear fácilmente popups 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">Hello, world!</div>

<script type="text/javascript">
  var my_popup = Clerk('ui', 'popup', '#my-popup');
  
  // mostrar popup
  my_popup.show(); 
  /* o */
  Clerk('ui', 'popup', '#my-popup', 'show');
  
  // ocultar popup
  my_popup.hide(); 
  /* o */
  Clerk('ui', 'popup', '#my-popup', 'hide');
</script>

Lee más sobre el UI de Popup aquí.

Exclusión de productos #

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

<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 al Clerk Block donde quieras evitar duplicados. El valor debe ser un selector CSS de los otros snippet(s) de los que quieres 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 #

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

Los eventos te permiten configurar 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 con sesión iniciada en una configuración B2B. Un evento puede ejecutarse justo después de que la API de Clerk haya terminado de renderizar, lo que te permite obtener precios personalizados y agregarlos a los elementos del 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 perjudicar el SEO. Al usar renderizado en el cliente y carga optimizada, equilibra velocidad, rendimiento y visibilidad en buscadores.

SEO y Velocidad #

Es un error común pensar que las funciones JavaScript como Clerk.js perjudican el rendimiento o el SEO. Las herramientas automatizadas a menudo pasan por alto optimizaciones como caché, carga paralela y gestión del lado del servidor.

Beneficios de Integración Clerk.js #

El script de Clerk.js (≈ 37 - 38 KB) se carga de forma asíncrona, lo que permite a tu sitio renderizar mientras Clerk se inicializa.
Los elementos Clerk se renderizan en el cliente, por lo que tu HTML base permanece cacheable y los componentes dinámicos se inyectan solo después de la carga.
Esto permite un caching del lado del servidor eficiente 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 el tiempo de carga de la página.
El impacto real suele provenir de imágenes adicionales mostradas en recomendaciones, no del script en sí. Para minimizar el impacto:
- Usa formatos eficientes y de tamaño adecuado como WebP.
- Redimensiona imágenes para adaptarse a las dimensiones de visualización (p.ej. 400×400 px → 420×420 px máximo).
Para evitar shifts de layout (CLS), reserva espacio para el contenido de Clerk que se inyectará.

Ejemplo:

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

Consideraciones de SEO #

Entender cómo Clerk.js interactúa con los motores de búsqueda ayuda a asegurar que tu implementación ofrezca buena experiencia de usuario y visibilidad.

Enlazado y Rastreabilidad #

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 por JavaScript, debes verificar cómo los crawlers los interpretan.
Los enlaces correctamente rastreados mejoran la rastreabilidad y permiten que los motores descubran e indexen más páginas.

Distribución de PageRank #

Cuando los motores pueden rastrearlos, los enlaces de Clerk.js ayudan a distribuir el equity de enlaces (PageRank) entre páginas clave.
Esto mejora la visibilidad y el ranking de páginas de producto y categoría.

Beneficios observados #

Una integración correcta de Clerk.js puede correlacionarse con estructuras de enlazado interno más sólidas, lo que puede mejorar la visibilidad en resultados de búsqueda.
Los tableros de Clerk.io ofrecen analíticas sobre influencia en pedidos, incremento de conversión y contribución al ingreso desde 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 así prevenir cambios de layout.
Monitorea métricas reales en lugar de basarte solo en puntuaciones automáticas. Utiliza los tableros 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 #

Snippets #

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 #

Renderizado Personalizado #

Depuración #

Métodos de activación #

Opciones de Configuración #

Almacenamiento en Sesión #

UI Kit #

Instant Search #

Search Page #

Category Page #

Facets #

Exit Intent #

Popup #

Exclusión de productos #

Excluir IDs específicos #

Evitar duplicados #

Eventos #

SEO y Rendimiento #

SEO y Velocidad #

Beneficios de Integración Clerk.js #

Impacto en el Rendimiento #

Consideraciones de SEO #

Enlazado y Rastreabilidad #

Distribución de PageRank #

Beneficios observados #

Buenas Prácticas Recomendadas #