FAQ

¿Tienes problemas con tu integración de Shopify? Esta FAQ cubre los problemas más comunes y sus soluciones, desde la conversión de divisas hasta la ubicación de los 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 según la colocación, puedes quitar el tamaño fijo sincronizado y solicitar un nuevo ancho en la URL.

Ejemplo (reemplaza 600x600 por el tamaño de imagen predeterminado que hayas configurado):

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

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

Conversión de divisas #

La conversión de divisas integrada de Shopify facilita la lectura del símbolo de moneda y la tasa de cambio desde la tienda online.

Por defecto, Clerk.js para Shopify viene acompañado de un formatter que funciona siempre que tu aplicación de terceros use el objeto de divisas integrado de Shopify.

Solución estándar #

Debes usar un formatter en tus Designs para convertir precios.

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

Al usar 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 Text donde quieras que aparezca el precio.

2. Agrega el siguiente código Liquid para mostrar el precio basado en el currency_converter dentro del componente de texto:

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

Modo código #

1. En my.clerk.io, ve a 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 API personalizada #

Aviso: Esta es una solución muy personalizada para obtener conversiones de precios si no hay datos del API de Shopify. Úsala solo si tienes una configuración específica y personalizada para conversiones según cambios de 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 mostrar dentro del contenido devuelto por la API de Clerk.

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

• Una colección que contenga todos los productos.

• Un layout alternativo para renderizar la información de la colección en formato JSON.

• Una clase JavaScript que recopila los datos disponibles en la colección.

• Un snippet de JavaScript que consume los datos para los IDs de producto relevantes en un resultado dado y los coloca dentro de un div en la plantilla.

Crear colección #

Para asegurarte de tener 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 hará que reciba la ruta /collection/clerk-api en el frontend.

La condición de 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 deseas usar.

En la sección de plantillas en el panel izquierdo, presiona Add new Template.

En la ventana emergente, selecciona collection como tipo de recurso.

Selecciona liquid como 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 agregar campos al producto en esta plantilla según sea necesario.

Agregar clase JS #

Para obtener los datos de tu colección y prepararlos para su uso, coloca todo el contenido de index.js de la carpeta class de este proyecto, dentro de la etiqueta script que contiene Clerk.js en theme.liquid.

Debe verse 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 se ejecute cuando la página cargue.
</script>

Esta clase invalidará los datos basándose en timestamps y divisas, sin necesidad de que cambies el código.

El tiempo antes de la invalidación es de 12 horas desde la última vez que se construyeron los datos.

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

Añadir función de plantilla #

Incluye template.js en la plantilla de diseño usada.

La función obtiene los datos cuando están disponibles y los coloca en elementos hijos específicos dentro de cada mosaico de producto.

El ejemplo incluye los campos list_price y price.

Cosas a tener en cuenta: Si necesitas usar campos diferentes a price y list_price, agrégalos en collection.json.liquid y luego edita tanto template.html como template.js para consumir esos campos también. Nunca deberías tener que editar la Clase descrita en el paso 3.

Encontrar archivos de tema #

Shopify cuenta con más de 100 temas diferentes para diseñar y personalizar tu tienda online.

Cada tema funciona de la misma forma: personalizas los archivos del tema para obtener un resultado específico en tu tienda.

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

Shopify te proporciona 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 contiene el código de la página de búsqueda, probablemente tendrá ‘search’ en el nombre.

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 correspondiente para ver si coinciden.

Esto se puede hacer en Google Chrome haciendo clic derecho en cualquier sección de la página y seleccionando ‘Inspect’.

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

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

Recomendaciones en el cajón del carrito #

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 de manera diferente según el tema de Shopify. Está diseñada específicamente para temas donde el carrito forma parte del DOM en todas las páginas pero permanece oculto hasta que el usuario lo abre.

Mostrar Clerk Recommendations en el cajón del carrito en Shopify es una excelente manera de mostrar productos adicionales a los compradores antes de iniciar el proceso de pago.

1. Edita el código de tu tema de Shopify en Online Store > Themes > Edit code.

2. Busca el archivo donde está la plantilla del cajón del carrito (normalmente llamado cart-drawer.liquid o similar).

3. Inserta un snippet de Clerk Recommendations desde Recommendations > Elements.

4. Cambia el nombre de 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 line_item in cart.items %}{% if forloop.index0 > 0 %}, {% endif %}{{ line_item.product.id }}{% endfor %}]"></span>

5. Junto con el snippet anterior, incluye un script para renderizar Clerk Recommendations cuando el usuario abra el carrito. Una forma es usar un MutationObserver. El siguiente script incluye todos estos elementos y te sirve como ejemplo de enfoque:

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

    // Agrega todos los nombres de clase del cajón del carrito, cuando esté abierto
    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 para 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;
                    }
                }

            }
        }
    };

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

    // Comienza a observar el nodo objetivo para las mutaciones configuradas
    clerk_observer.observe(targetNode, config);
</script>

Tu archivo del cajón del carrito debería verse así:

Autenticación HTTP #

La autenticación HTTP se usa comúnmente en sitios de pruebas para evitar visitantes no deseados.

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

Puedes solucionarlo 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 de la siguiente manera:

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 los datos de productos, categorías y ventas a Clerk.

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

A continuación tienes 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 nombre de usuario y contraseña como parte de la URL de importación:

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

Error de permisos #

Este error normalmente ocurre si no has dado Read Access a Store content like articles, blogs, comments, pages and redirects en tu Private App.

Para solucionarlo:

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

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

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

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

Manejo de require.js #

Esta guía solo aplica al usar Clerk.js 1.

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

Cuando esto sucede, verás el siguiente error en tu consola:

Uncaught ReferenceError: Clerk is not defined

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

Incluir en Require.js #

La mejor manera es intentar que Require.js reconozca Clerk.

Puedes hacerlo insertando require(['clerk'], function() {}); en la parte inferior del tracking script:

Ignorar Require.js #

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

Puedes hacerlo insertando window.__clerk_ignore_requirejs = true; en la parte superior del tracking script:

Después de usar uno de estos métodos, Require.js ahora será compatible con Clerk.

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 en cualquier tienda online.

Sin embargo, como ambas versiones funcionan de forma ligeramente distinta, debes seguir estos pasos para actualizar con éxito.

Las dos principales diferencias en Clerk.js 2 son:

• Los Designs en my.clerk.io usan el lenguaje de plantillas Liquid, pero también se pueden crear fácilmente con el Editor de Diseño.

• El script debe insertarse justo antes de la etiqueta </head> en la plantilla de tu tienda.

Crear diseños #

Como Clerk.js 2 tiene un enfoque distinto para los Designs, debes crear unos nuevos.

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

• Usa el intuitivo Editor de Diseño para crear nuevos Designs, como se describe en los puntos siguientes.

• Convierte tus antiguos Designs. Sigue esta guía para ver 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, ponle un Name a tu Design (recomendamos agregar “V2” para que sea obvio que usas Clerk.js 2).

3. Elige el tipo de Design.

4. Haz clic en Publish Design cuando termines, y ve al Step 2 de la guía.

5. En el Design Editor, haz clic en cualquiera de los elementos existentes (nombre, imagen, botón, etc.) para editarlo, o agrega nuevos elementos para mostrar más información de los productos.

6. Haz clic en Publish. Esto hará que temporalmente no se muestren hasta que termines el Step 2. Elige el nuevo Design para todos los Elements que deban ser actualizados.

7. Ve a Recommendations/Search > Elements y cambia tu Clerk Element para que utilice tu nuevo Design.

Ahora estás listo para cambiar a Clerk.js 2.

Reemplazar script #

1. Localiza el archivo de plantilla que se usa para mostrar todas las páginas de la tienda, donde se encuentra el script original de Clerk.js, cerca de la parte inferior.

2. Elimina el script antiguo del archivo:

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

4. Copia este código e insértalo justo antes de la etiqueta </head> en la plantilla:

5. Guarda tu plantilla.

¡Felicidades! ¡Ahora tienes la configuración mejorada 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 del cliente (Customer Events Access) #

Cuando te ayudamos a configurar o solucionar problemas de seguimiento de pedidos a través de los píxeles de Shopify, es posible que te pidamos acceso al área de eventos del cliente en el 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 que quieras actualizar).
3. Desplázate a Store settings y habilita:
   • View customer events
   • Manage and add custom pixels
4. Haz clic en Save.

Estos permisos permiten que nuestro equipo vea la sección de eventos del cliente y gestione el pixel de Clerk, para que podamos verificar que el seguimiento de pedidos está funcionando correctamente.