Clerk.js

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 manera asíncrona. Esto significa que el resto de la página no depende de una respuesta de la API antes de cargar.
• A menudo es más rápido, ya que tu servidor puede comenzar a renderizar la página en paralelo con Clerk.js realizando llamadas y renderizando 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 el useragent, combinado con una sal de tienda única que rota cada 30 días.

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

<!-- Inicio de la herramienta de personalización de comercio electrónico de Clerk.io - 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>
<!-- Fin de la herramienta de personalización de comercio electrónico de Clerk.io - www.clerk.io -->

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

Fragmentos #

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

Luego utiliza los atributos del fragmento para construir una llamada a la API mientras obtiene la clave API de la configuración en el script de inicialización.

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

Los visuales son manejados por el Diseño, que también es referenciado por el fragmento.

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 fragmento.

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

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

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

Los fragmentos también pueden simplificarse para incluir solo una referencia a un bloque de Contenido, utilizando la sintaxis data-template="@content-block-id":

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

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

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

Inyección #

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

Lee más sobre Inyección aquí.

Configuración #

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

IDs de visitantes #

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 el seguimiento durante un período de tiempo más largo.

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

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

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

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

Idioma #

Configura Clerk.js con el idioma escrito del sitio web. Esto se utiliza para que Clerk.io maneje correctamente las reglas gramaticales en la búsqueda y para obtener las traducciones correctas cuando usas feeds multilingües.

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

Funciones de Diseño #

Clerk.js admite la adición de Formatters y Globals, que se pueden usar para crear funcionalidad personalizada de JavaScript para tus ámbitos de diseño.

Formatters #

Estos se utilizan para influir o cambiar atributos. Por ejemplo, es posible que solo desees mostrar los primeros 40 caracteres de una descripción, o que necesites calcular un porcentaje de descuento específico según el tipo de cliente que haya iniciado sesión.

Globals #

Estos están destinados a ser utilizados con datos del frontend a los que deseas acceder en los diseños. Esto podría ser ejemplos como la cantidad restante necesaria para lograr envío gratuito, el nombre de un cliente que ha iniciado sesión, 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">SABLE DE LUZ VERDE</div>
<div class="price">$1999.99</div>

Seguimiento de correos electrónicos #

Clerk.js puede recoger correos electrónicos automáticamente en la sesión del cliente para ser utilizados para personalizar recomendaciones de correo electrónico incluso si aún no han realizado un pedido.

Esto se hace configurando 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 registrará con log/email cuando un visitante escriba una dirección de correo electrónico en uno 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 con Aplicaciones de Página Única (SPA), Aplicaciones Web Progresivas (PWA) y otras aplicaciones que no utilizan cargas de página tradicionales.

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

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

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

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

Depuración #

Clerk.js tiene un modo de depuración incorporado que registrará varias informaciones en la consola, dependiendo del nivel que elijas. Se configura directamente en la URL:

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

El depurador tiene 4 parámetros:

Kit de UI #

Clerk.js incluye un conjunto de herramientas de UI para elementos importantes que se pueden usar para mejorar la experiencia del usuario. Estos a menudo ahorran tiempo de desarrollo para configuraciones personalizadas.

Búsqueda instantánea #

Una parte clave de una gran experiencia de búsqueda en comercio electrónico es obtener resultados inmediatamente al comenzar a escribir. Nuestro componente de UI de Búsqueda Instantánea hace que esta experiencia de usuario sea rápida y fácil de construir.

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

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

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

Página de búsqueda #

Una parte clave de una gran experiencia de búsqueda en comercio electrónico es obtener buenos resultados de búsqueda. Nuestra Página de Búsqueda hace que esta experiencia de usuario sea rápida y fácil de construir.

La Página de Búsqueda te permite crear una página completa que muestra las mejores coincidencias posibles para cualquier consulta dada.

<span 
  class="clerk"
  
  data-api="search/search"
  data-limit="40"
  data-labels='["Página de Búsqueda"]'
  data-query="INSERT_QUERY_HERE"
  data-orderby="INSERT_SORTING_ATTRIBUTE"
  data-order="asc_OR_desc">>
  
  <div class="product-search-result-list">
    <div>Productos que coinciden con <i>{{ query }}</i></div>
    
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Comprar ahora</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#{{ content.id }}', 'more', 40);">
          		Mostrar más resultados
    		</div>
    {% endif %}
  </div>
</span>

Lee más sobre la herramienta de UI de Página de Búsqueda aquí.

Página de categoría #

Una página de categoría bien estructurada es clave para un negocio de comercio electrónico exitoso. Nuestra Página de Categoría hace que esta experiencia de usuario sea rápida y fácil de construir. Esto te permite crear una página completa que muestra los mejores resultados posibles para cualquier categoría.

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

Lee más sobre la herramienta de UI de Página de Categoría aquí.

Facetas #

Clerk.js viene con soporte incorporado para navegación dinámica con facetas tanto para búsqueda como para categorías. Cualquier atributo de producto que nos envíes puede usarse como facetas.

Aquí hay 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": "PRECIO-TRADUCCIÓN", "categories": "CATEGORÍAS-TRADUCCIÓN", "brand": "MARCA-TRADUCCIÓN"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="Ver más"
  data-facets-searchbox-text="Buscar por "
  data-facets-design="133995">
</span>

Lee más sobre la herramienta de UI de Facetas aquí.

Intención de salida #

El popup de intención de salida reacciona cuando un visitante intenta abandonar tu sitio al mover el mouse cerca de la parte superior de la ventana del navegador. Aparece y muestra productos interesantes, convirtiendo posiblemente a un visitante que se va en un cliente comprador.

Cualquier bloque de Contenido puede ser activado ante la intención de salida de un visitante añadiendo el atributo data-exit-intent="true" al fragmento.

<span
  class="clerk"
  
  data-api="recommendations/visitor/complementary"
  data-limit="20"
  data-labels='["Intención de Salida / Popup"]'
  
  data-exit-intent="true">
</span>

Lee más sobre la herramienta de UI de Intención de Salida aquí.

Popup #

El Kit de UI contiene una biblioteca de popup simple para crear fácilmente popups simples pero amigables con el usuario con cualquier contenido. Cualquier elemento HTML en tu sitio web 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 de UI de Popup aquí.

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 deslizadores.

Exclusión de IDs específicos #

Simplemente añade el atributo data-exclude al fragmento. El contenido de data-exclude debe ser una lista de los IDs de producto que no deseas que se muestren, es decir, los productos en el carrito de compras del cliente o una lista de productos que no se les permite ver.

<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 Clerk donde quieras eliminar el duplicado. El valor del atributo debe ser un selector CSS para el otro(s) fragmento(s) de los que se deben prevenir duplicados.

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

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

Lee más sobre la herramienta de UI de Exclusión de Productos aquí.

Eventos #

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

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

Un ejemplo común es cargar precios personalizados para un cliente que ha iniciado sesión en una configuración B2B. Un evento puede ejecutarse inmediatamente después de que la API de Clerk haya terminado de renderizar, permitiéndote obtener precios personalizados para un cliente y 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í.