Preguntas frecuentes

¿Tienes problemas con tu integración de Shopify? Este FAQ cubre los problemas más comunes y sus soluciones, desde conversión de moneda hasta ubicación de archivos de tema.

Tamaños de imagen #

Las URLs de imágenes de Shopify pueden incluir dimensiones fijas desde la sincronización, por ejemplo _600x600.

Si tu diseño necesita un tamaño de salida diferente por ubicación, puedes eliminar el tamaño fijo sincronizado y solicitar un nuevo ancho en la URL.

Ejemplo (reemplaza 600x600 por tu tamaño de imagen predeterminado configurado):

{{ product.image
  | replace '_600x600.' '.'
  | replace '?v=' '?width=350&v=' }}

Esto es útil cuando un diseño utiliza múltiples formatos de imagen (por ejemplo tarjetas de producto y placements grandes tipo hero) y deseas evitar sincronizar múltiples atributos de imagen.

Conversión de moneda #

La Conversión de Moneda incorporada de Shopify facilita la lectura del símbolo y la tasa de cambio de la tienda online.

Por defecto, Clerk.js para Shopify viene incluido con un formatter que funciona siempre que tu app de terceros use el objeto de moneda incorporado de Shopify.

Solución estándar #

Debes usar un formatter en tus Designs para convertir los precios.

Este ejemplo usa nuestro lenguaje estándar de plantillas aquí.

Al utilizar conversiones de moneda y símbolos, Clerk.js detecta configuraciones como idioma, moneda y código de país.

Los siguientes ejemplos muestran cómo funcionan los distintos componentes.

Editor de diseño #

1. Crea un componente de Texto donde quieres que se muestre el precio.
2. Agrega el siguiente código Liquid para mostrar el precio basado en el convertidor de moneda dentro del componente de texto:

{{ currency_symbol }}{{ item.price | currency_converter }}

Modo código #

1. En my.clerk.io, entra en Search/Recommendations > Designs y haz clic en Edit Design para tu diseño.
2. Reemplaza el formatter existente money o money_eu para los precios por currency_converter.
3. Haz clic en Update Design.
4. Ahora podrás ver los precios convertidos y el símbolo de moneda en tu diseño.

Solución de API personalizada #

Aviso: Esta es una solución muy personalizada para obtener conversiones de precios si no hay datos desde la API de Shopify. Sólo úsalo si tienes una configuración personalizada para las conversiones de precio basada en cambios geo-IP.

Esta es la documentación de la solución frontend en Github.

Esta sección cubre cómo obtener datos contextuales en tiempo real para mostrarlos dentro del contenido devuelto por la API de Clerk.io.

El patrón de diseño se compone de las siguientes partes:

• Una colección conteniendo todos los productos.
• Un layout alternativo para renderizar la información de la colección en formato JSON.
• Una Clase de JavaScript que recoja los datos disponibles en la colección.
• Un Snippet de JavaScript que utilice estos datos para los product IDs relevantes en un resultado dado y los coloque dentro de un div en la plantilla.

Crear colección #

Para asegurar que tienes una colección con todos los productos posibles, crea una colección con una condición que cumplan todos los productos.

La colección debe llamarse Clerk api, lo que le dará la ruta /collection/clerk-api en el frontend.

La condición para la colección debe ser algo como price > -1000000.

Crear layout alternativo #

Crea un layout alternativo para mostrar tus datos usando la colección.

Para ello, primero edita el código del tema que quieras usar.

En la sección de plantillas a la izquierda, presiona Add new Template.

En el popup, selecciona collection como tipo de recurso.

Selecciona liquid para el tipo de archivo.

Escribe json en el campo inferior, para que el nombre de la plantilla creada sea collection.json.liquid.

El contenido de este archivo debe ser el archivo collection.json.liquid que se encuentra en la carpeta liquid de este proyecto.

Puedes añadir campos al producto en esta plantilla según lo necesites.

Añadir clase JS #

Para recoger los datos de tu colección y prepararlos para su uso, coloca el contenido completo de index.js en la carpeta class de este proyecto, dentro del tag script que contiene Clerk.js que has puesto en theme.liquid.

Debe verse algo así:

<script>
  // Clerk.js Injection Code
  // Clerk Config with Key and Formatters
  // Class from this project
  clerk_shopify_api.init()
  // Finalmente init() para la clase para asegurar que corre al cargar la página.
</script>

Esta clase invalidará los datos según timestamps y monedas, sin que necesites cambiar el código.

El tiempo antes de la invalidación es de 12 horas desde la última generación de datos.

Cualquier cambio en el contexto de moneda también invalida los datos.

Añadir función de plantilla #

Incluye el template.js en la plantilla de diseño utilizada.

La función toma los datos disponibles y los coloca en elementos hijos específicos dentro de cada cuadro de producto.

El ejemplo incluye los campos list_price y price.

Aspectos a tener en cuenta: Si necesitas usar campos diferentes a price y list_price, deberás agregarlos en collection.json.liquid y luego editar template.html y template.js para que también los utilicen. Nunca deberías tener que editar la Clase descrita en el paso 3.

Encontrar archivos de tema #

Shopify alberga más de 100 temas diferentes para estilizar y personalizar tu tienda online.

Cada tema funciona de la misma forma: personalizas los archivos del tema para obtener el resultado deseado en tu tienda.

Sin embargo, los nombres de los archivos de tema cambian de un tema a otro.

Shopify te da un campo de búsqueda para encontrar fácil y rápidamente el archivo de tema que buscas.

Si no sabes el nombre del archivo que buscas, puedes usar el campo de búsqueda para ayudarte a localizarlo.

Por ejemplo, si buscas el archivo que tiene el código para la página de búsqueda, es probable que tenga ‘search’ en el nombre del archivo.

Si no estás seguro de haber encontrado el archivo correcto, puedes comparar el HTML en el archivo de tema con el HTML en la página relevante para ver si coinciden.

Esto puede hacerse en Google Chrome haciendo clic derecho sobre cualquier parte de la página y seleccionando ‘Inspeccionar’.

Luego puedes inspeccionar el HTML en la página y revisar si la clase/ID de los elementos es la misma en el archivo que en la página.

Si necesitas más ayuda con esto, también puedes contactar a nuestro equipo de soporte.

Recomendaciones en el cart drawer #

Se recomienda encarecidamente que la instalación la realice un desarrollador de Shopify.

Esta guía describe una solución altamente personalizada que puede comportarse diferente según el tema de Shopify. Está diseñada específicamente para themes donde el carrito es parte del DOM en cada página pero permanece oculto hasta que el usuario lo abre.

Mostrar Clerk.io Recommendations en el cart drawer en Shopify es una excelente forma de mostrar productos adicionales a los compradores antes de que inicien el proceso de checkout.

1. Edita el código de tu tema de Shopify en Online Store > Themes > Edit code.
2. Encuentra el archivo donde se encuentra la plantilla del cart drawer (usualmente llamado cart-drawer.liquid o similar).
3. Inserta un snippet de Clerk.io Recommendations desde Recommendations > Elements.
4. Renombra la clase de clerk para controlar el renderizado. Por ejemplo, llamándola clerk_m:

<span
  class="clerk_m"
  data-template="@cart-others-also-bought"
  data-products="[{% for item in cart.items %}{{ item.product_id }}{% unless forloop.last %}, {% endunless %}{% endfor %}]"
></span>

1. Junto al snippet anterior, incluye un script para renderizar Clerk.io Recommendations cuando el usuario abra el carrito. Una forma de hacerlo es usar un MutationObserver. El siguiente script incluye todos estos elementos, como ejemplo de cómo abordarlo:

<script>
    // Selecciona el nodo que se observará para mutaciones
    const targetNode = document.querySelector("cart-drawer.drawer");

    // Agrega todos los nombres de clase del cart drawer cuando se abre
    const targetNodeClasses = "drawer animate active";

    // Opciones para el observer (qué mutaciones observar)
    const config = { attributes: true };

    let cartFetched = false;
    let previousitemsID = [];
    
    // Función para obtener datos del carrito
    async function fetchCartData() {
        const response = await fetch("/cart.js");
        const data = await response.json();
        let itemsID = [];
        let cartItems = data.items;
        for (var i = 0; i < cartItems.length; i++) {
            itemsID.push(cartItems[i].product_id);
        }
        return itemsID;
    }

    // Función callback a ejecutar cuando se observan mutaciones
    const callback = async (mutationList, observer) => {
        for (const mutation of mutationList) {
            if (mutation.type === "attributes") {
                if (targetNode.className == targetNodeClasses && !cartFetched) {
                    cartFetched = true;
                    try {
                        const itemsID = await fetchCartData();
                          if (JSON.stringify(previousitemsID) != JSON.stringify(itemsID)) {
                            await Clerk('content', '.clerk_m', 'param', { products: itemsID })
                            previousitemsID = itemsID
                          }
                    } catch (error) {
                        console.error(error);
                    } finally {
                        cartFetched = false;
                    }
                }

            }
        }
    };

    // Crear una instancia de observer vinculada a la función callback
    const clerk_observer = new MutationObserver(callback);

    // Comenzar a observar el nodo objetivo
    clerk_observer.observe(targetNode, config);
</script>

Guarda el archivo actualizado del cart drawer y prueba que las recomendaciones de Clerk aparezcan cuando se agregue un producto al carrito.

Autenticación HTTP #

La autenticación HTTP suele usarse en sitios de staging para evitar visitas no deseadas.

Esto bloqueará el importador de Clerk.io y mostrará un error 401 Unauthorized en el log de sincronización.

Puedes solucionar esto insertando la información de autenticación en la URL de importación.

En my.clerk.io > Data > Configuration, actualiza tu URL de importación así:

https://USER:PASS@www.ewoksRus.com

Errores comunes de sincronización #

Al importar datos con la integración de Shopify, el servidor de tu tienda es responsable de enviar datos de productos, categorías y ventas a Clerk.io.

Sin embargo, en algunos casos, la configuración del servidor puede impedir que el Importer tenga acceso, provocando un error en Data Sync.

A continuación se muestra una lista de los errores más comunes y cómo solucionarlos.

401 Unauthorized #

Este error ocurre si tu tienda o entorno de desarrollo requiere autenticación HTTP para acceder.

Esto se soluciona insertando el Username y Password como parte de la URL de importación:

http://username:password@awesomeshop.myshopify.com

Error de permisos #

Este error suele ocurrir si no has dado Read Access a Store content like articles, blogs, comments, pages and redirects en tu App Privada.

Para solucionarlo:

1. Inicia sesión en Shopify y ve a Apps > Manage Private Apps > Clerk.io (o el nombre que diste a la App).

2. Desplázate hasta Admin API Permissions, y haz clic en Review disabled Admin API permissions.

3. Encuentra Store content like articles, blogs, comments, pages and redirects y elige Read access:

4. Ve hasta la parte superior de la página y haz clic en Save.

Manejo de require.js #

Esta guía solo aplica cuando uses Clerk.js 1.

En algunas configuraciones, Require.js impide que Clerk.js cargue, lo que significa que no se mostrarán ni sliders ni resultados de búsqueda.

Cuando esto ocurra, verás el siguiente error en la consola:

Uncaught ReferenceError: Clerk is not defined

Hay dos formas de manejar Require.js. Ambas requieren que modifiques el tracking-script, que normalmente se inserta en index.liquid.

Incluir en Require.js #

La mejor opción es intentar que Require.js reconozca Clerk.io.

Inserta require(['clerk'], function() {}); al final del tracking script.

Ignorar Require.js #

Si la solución anterior no funciona, es posible ignorar Require.js.

Inserta window.__clerk_ignore_requirejs = true; al inicio del tracking script.

Después de usar una de estas soluciones, Require.js será compatible con Clerk.io.

Actualización a Clerk.js 2 #

Clerk.js 2 es una versión más rápida y flexible de nuestra librería JavaScript.

Facilita la instalación de Clerk.io en cualquier tienda online.

Sin embargo, dado que las dos versiones funcionan de manera ligeramente diferente, debes seguir estos pasos para actualizar con éxito.

Las dos principales diferencias en Clerk.js 2 son:

• Los Designs en my.clerk.io utilizan el lenguaje de plantillas Liquid, aunque también se pueden crear fácilmente usando el Design Editor.
• El script debe insertarse justo antes de la etiqueta </head> en la plantilla de tu tienda online.

Crear diseños #

Dado que Clerk.js 2 tiene un enfoque diferente para los Designs, debes crear nuevos.

Puedes crear tus Designs de Clerk.js 2 de dos formas:

• Usar el intuitivo Design Editor para crear nuevos Designs, como se describe en los siguientes puntos.
• Convertir tus antiguos Designs. Sigue esta guía para saber cómo hacerlo.

Opción Editor de diseño #

1. Ve a my.clerk.io > Recommendations/Search > Designs > New Design.
2. En la siguiente pantalla, da a tu Design un Nombre (recomendamos añadir “V2” para que sea claro que usas Clerk.js 2).
3. Elige el Tipo de Design.
4. Haz clic en Publish Design cuando termines, y ve al Paso 2 en la guía.
5. En el Design Editor, haz clic en cualquiera de los elementos existentes como el nombre, imagen, botón, etc. para editarlo, o añade nuevos elementos al Design para proporcionar más información sobre los productos.
6. Haz clic en Publish. Esto hará temporalmente que no se muestren en tu tienda hasta que termines el Paso 2. Elige el nuevo Design para todos los Elements que deban actualizarse.
7. Ve a Recommendations/Search > Elements y cambia tu Element de Clerk.io para usar tu nuevo Design.

Ya estás listo para pasar a Clerk.js 2.

Reemplazar script #

1. Ubica el archivo de plantilla que se utiliza para mostrar todas las páginas de la tienda, y donde se encuentra el script original de Clerk.js cerca del final.

2. Elimina el script anterior del archivo:

3. Ve a my.clerk.io > Developers > Clerk.js.. Esta página ahora contiene tu nuevo código de seguimiento Clerk.js 2.

4. Copia este código y pégalo justo antes de la etiqueta </head> en la plantilla:

5. Guarda tu plantilla.

¡Felicidades! ¡Ahora tienes operativa la nueva y mejorada implementación de Clerk.js 2!

Puedes ver la documentación completa de Clerk.js 2 aquí: https://docs.clerk.io/docs/clerkjs-quick-start

Acceso a eventos de cliente #

Cuando te ayudamos a configurar o solucionar problemas de seguimiento de pedidos mediante píxeles de Shopify, es posible que pidamos acceso al área de eventos de cliente en tu panel de administración de Shopify.

Sigue estos pasos para otorgar los permisos necesarios:

1. En Shopify, ve a Settings > Users and permissions.
2. Haz clic en el miembro del staff llamado Clerk.io (o el usuario de staff que quieras actualizar).
3. Ve a Store settings y habilita:

• View customer events
• Manage and add custom pixels

4. Haz clic en Save.

Estos permisos permiten a nuestro equipo ver la sección Customer events y gestionar el pixel de Clerk.io para poder verificar que el seguimiento de pedidos funciona correctamente.