Extension

Configura los ajustes de tu extensión de Magento 2, gestiona las opciones de sincronización de datos y personaliza las funciones de Search, Recommendations y registro de eventos (logging). Esta guía también cubre la instalación mediante Toolbox Script, cómo actualizar y desinstalar.

Instalando con toolbox #

El Clerk Toolbox Script ha sido creado para facilitar la instalación de la extensión Clerk en tu tienda Magento sin usar Magento Connect.

El Toolbox Script se ejecuta directamente desde un terminal.

Sugerimos estos:

- Apple: iTerm, tendrás que descargarlo de Internet;

- Windows: Command Prompt, ya está instalado en tu ordenador.

El script también crea una copia de seguridad de la carpeta de Magento2 para que pueda restaurarse si algo sale mal.

Lo que necesitas #

Para instalarlo, necesitas acceso SSH o SFTP a tu tienda online, incluidos tu Nombre de usuario y Contraseña.

Navegando a la carpeta #

1. Comienza iniciando sesión en tu servidor de Magento a través de un terminal, utilizando tu Nombre de usuario y Dominio así:

ssh Stefan@mywebshop.com

2. Se te pedirá que introduzcas la contraseña de tu usuario (el terminal no mostrará ningún feedback mientras la escribes, pero la está registrando igualmente).

Navega a la carpeta raíz de Magento2. Puedes hacerlo escribiendo:

cd /var/www/html

y escribiendo:

ls

Esto te mostrará una lista de carpetas para ayudarte a encontrar la correcta:

En la lista de carpetas, busca la carpeta correcta, en este caso sería magento2.

En este punto, solo necesitas entrar en la carpeta, puedes hacerlo escribiendo:

cd NAME_FOLDER

NAME_FOLDER se sustituye por el nombre real de la carpeta.

Instalando la extensión #

1. Una vez que estés en tu carpeta raíz, necesitas descargar el Toolbox Script con esta línea:

sudo wget https://raw.githubusercontent.com/clerkio/clerk-magento2/master/clerk_toolbox_magento2.sh

2. Después, escribe esta línea para ver la lista de opciones disponibles dentro del Toolbox:

sh clerk_toolbox_magento2.sh

3. Como quieres instalar la extensión, utiliza -i junto con el número de versión más reciente de la extensión. Escribe esta línea:

sudo sh clerk_toolbox_magento2.sh -i

4. Ahora se te pedirá que escribas tu contraseña. Después de hacerlo, el script hará una copia de seguridad de tu carpeta de Magento2 y comenzará a instalar la extensión:

5. ¡Listo! Ahora la extensión está instalada y puedes configurarla en el backend de Magento2.

Comandos opcionales #

Desinstalación

El Toolbox también te permite desinstalar la extensión. Puedes hacerlo con esta línea:

sudo sh clerk_toolbox_magento2.sh -u

Restaurar

En caso de que algo salga mal en tu tienda online, siempre puedes restaurarla usando la copia de seguridad que se realiza al instalar la extensión.

Utiliza esta línea para hacerlo:

sudo sh clerk_toolbox_magento2.sh -r

Backup

Al instalar la extensión, el script siempre creará primero una copia de seguridad, pero también puedes crear una copia de seguridad por separado con esta línea:

sudo sh clerk_toolbox_magento2.sh -b

Ajustes de my.clerk.io #

Para acceder y modificar los ajustes de datos de tu Magento 2 en Clerk, ingresa en my.clerk.io, haz clic en “Data” desde el menú lateral izquierdo y luego ve a “Configuration”.

Nota: La información sobre la extensión Clerk para Magento 2, disponible a través del panel de administración de Magento, está más adelante en este artículo.

Aquí puedes establecer la URL de tu tienda, el tamaño de página de tus sincronizaciones de datos, así como la hora del día en que tus datos deben sincronizarse con Clerk (por defecto es “cuando sea necesario”).

Ajustes de la extensión #

Si usas la v6.7.0 o una versión posterior de la extensión, podrás acceder a los siguientes ajustes de dos maneras tras agregar tus Public y Private Keys a la extensión:

• Desde el backend de Magento2 en Stores > Settings > Configuration > Clerk > Configuration

• Desde my.clerk.io, bajo Developers > Extensions

No importa dónde realices los cambios, ya que la extensión sincronizará cualquier cambio realizado en my.clerk.io y viceversa.

En my.clerk.io también podrás ver la versión actual de tu extensión, tu plataforma y la versión de PHP.

Simplemente haz clic en “Edit” en cualquier ajuste para ver las opciones disponibles:

Descripción general #

Para acceder a tu extensión Clerk en Magento 2, entra en el portal de administración de tu tienda online y sigue la ruta Stores > Settings > Configuration > Clerk > Configuration

General #

Encontrarás el número de versión de tu Clerk Extension, así como las claves públicas y privadas de API de tu tienda en la sección General.

Para incluir Pages en tu sincronización de datos con Clerk, selecciona “Yes” en el siguiente menú desplegable y escribe cualquier campo adicional que desees incluir con los datos de tus páginas (por ejemplo, imágenes o tipo de página) separados por coma.

También puedes establecer el idioma predeterminado para los datos sincronizados de tu tienda en el último desplegable del apartado General.

Legacy Authentication #

Esta configuración controla si la extensión usa autenticación de cabecera JWT o el método antiguo de llave privada. Se recomienda desactivarlo, ya que JWT proporciona un flujo de autenticación más moderno y seguro para todas las solicitudes API entre Magento 2 y Clerk.io.

Store ID #

Este es un campo de configuración heredado que ya no se utiliza en instalaciones modernas de Clerk.io. Puede ignorarse con seguridad, ya que la extensión identifica y gestiona automáticamente los ámbitos de tienda utilizando las APIs nativas de tienda y sitio web de Magento.

Sincronización #

En la sección Synchronization del complemento de Clerk, tienes la opción de personalizar tus datos sincronizados de clientes, pedidos, carritos y productos.

Las opciones aparecen atenuadas y no están disponibles para actualizar cuando se usan los datos del sitio web, indicado por la casilla marcada a la derecha de cada sección.

Simplemente desmarca la casilla correspondiente para modificar.

• Use Real-time Updates: elige “Yes” para habilitar las actualizaciones en tiempo real para tus datos sincronizados con Clerk.

Con las actualizaciones en tiempo real habilitadas, el stock se actualiza ahora después de los pedidos, así como después de guardar productos en la administración de Magento 2.

• Collect Emails: selecciona “Yes” aquí para sincronizar los Emails de clientes.

• Collect Baskets: para recoger datos de carritos y sincronizarlos con Clerk, selecciona “Yes” aquí.

• En los siguientes dos desplegables, selecciona “yes” para sincronizar solo productos vendibles y/o solo sincronizar productos con visibilidad hacia Clerk.

• Si necesitas desactivar la sincronización de pedidos, puedes hacerlo eligiendo “Yes” en este menú desplegable.

Additional Fields #

Una lista separada por comas de atributos de producto adicionales que deseas sincronizar con Clerk.io (por ejemplo, color, size, material). Esto te permite utilizar estos atributos personalizados en tus diseños de recomendaciones de Clerk.io, filtros de búsqueda o campañas de Email.

Search Non-Indexed Attributes #

Cuando se activa, Clerk.io realizará una consulta más profunda para obtener valores de atributos personalizados que no están previamente indexados en la colección estándar de productos de Magento. Esto asegura que todos los campos personalizados solicitados se sincronicen correctamente, aunque puede requerir un poco más de recursos del servidor.

Piénsalo como si enviaras a un asistente muy educado a buscar en los estantes polvorientos del almacén en vez de solo leer la hoja de control junto a la puerta.

Track Returned Orders #

Al habilitar esta opción, la extensión registra la creación de credit memos en Magento 2. Los credit memos sincronizan los cambios de stock y rastrean los artículos devueltos en Clerk.io.

Image Type #

Este desplegable te permite seleccionar qué tipo y dimensiones de imagen de Magento (por ejemplo, imagen base, imagen pequeña o miniatura) deben enviarse a Clerk.io. Esto es muy útil para hacer coincidir la calidad y proporción de imagen con el tema y diseño específicos de tu tienda.

Sincronización de clientes #

Habilita la sincronización de datos de clientes seleccionando “Yes” en el desplegable de esta sección.

Si tienes atributos de cliente adicionales que deseas incluir en la sincronización con Clerk, escríbelos aquí como una lista separada por comas.

Sync Subscribers #

Al activar esta opción, los suscriptores de tu newsletter se sincronizan con Clerk.io.

Para los clientes registrados que también son suscriptores, la extensión actualiza automáticamente su perfil de cliente existente con subscribed: true e incluye su enlace único de cancelación de suscripción.

Para los suscriptores invitados (que se han suscrito al boletín pero no tienen una cuenta de cliente registrada), la extensión los sincroniza como perfiles independientes —que en Clerk.io se identifican simplemente por su dirección de Email— con un prefijo de ID SUB. Esto garantiza que se capte toda tu audience de suscriptores sin crear perfiles duplicados para clientes registrados. Esto es extremadamente útil para construir públicos completos de Email marketing y ejecutar campañas personalizadas.

Search #

Activa la página de Search de tu tienda seleccionando “Yes” en el desplegable aquí.

• Tras seleccionar “Enabled”, introduce el nombre de tu Search Page Element, que coincide con el campo data-template del código de inserción de tu Element en my.clerk.io. En este ejemplo, search-page.

• Puedes configurar el texto “load more” y “no results” que se mostrará escribiendo la frase deseada en estos campos de texto.

Include Categories #

Al activar esta opción, los resultados de categorías se incluyen directamente en tu página principal de búsqueda junto con los resultados de productos. Esto ayuda a los clientes a navegar tu tienda mostrando colecciones y categorías relevantes que coinciden con su consulta de búsqueda.

Number of Categories #

Establece el número máximo de resultados de categoría para mostrar en la página de búsqueda. Por ejemplo, al configurar esto en 5 se mostrarán hasta cinco categorías coincidentes, permitiendo que los usuarios accedan rápidamente a secciones relevantes de tu catálogo.

Number of Pages #

Establece el número máximo de resultados de páginas CMS o de contenido para mostrar en la página de búsqueda. Esto es ideal para mostrar publicaciones de blog, guías o páginas informativas (como políticas de devolución) junto con productos.

Pages Type #

Filtra los tipos de páginas CMS o de contenido que deben mostrarse en los resultados de búsqueda. Puedes elegir mostrar solo páginas CMS estándar, publicaciones de blog específicas o todas las páginas de contenido sincronizadas con Clerk.io.

Live search #

• Tras seleccionar “Enabled” en el desplegable para activar Live Search, selecciona si deseas mostrar Categories dentro de los resultados de búsqueda.

  • También puedes seleccionar el número de resultados de suggestions, categories y content para mostrar dentro de Live Search, además de los resultados de productos.

• Tienes la opción de elegir qué tipos de páginas se mostrarán como resultados, por ejemplo “CMS Pages”, “Blog Posts” o “All”.

• Puedes elegir la posición del desplegable de búsqueda en vivo desde tu caja de búsqueda con Dropdown Positioning.

• Proporciona el nombre del Element para tu búsqueda en vivo, que puedes encontrar junto a data-template en tu código de inserción Live Search dentro de tu Element en my.clerk.io. Seguramente será live-search.

• Por último, tienes la opción de indicar el Live Search Input Selector y el Form Selector, que puedes encontrar inspeccionando la caja de búsqueda de tu tienda con el navegador e identificando el ID o clase asociada con su input y formulario.

  • En este ejemplo, #search es el selector de input, y se usa el sitio web para identificar el selector de formulario.

Faceted navigation #

Para añadir facets a tu Search Page, primero asegúrate de seleccionar la casilla “Enabled” en Faceted Navigation.

• Haz clic en los atributos que deseas agregar a tus facets y guarda la configuración.

• Una vez añadidos, tus atributos aparecerán bajo Titles. En esta sección puedes crear el título que se mostrará para ese facet y la posición en la lista de facets en la que deseas que aparezca dicho atributo.

Facets In Url #

Al activar esta opción, los facets (filtros) de búsqueda seleccionados se añaden directamente a los parámetros de la URL del navegador. Esto permite a los clientes guardar en favoritos, actualizar o compartir sus resultados filtrados con otros, preservando exactamente su estado de filtro.

Multiselect Attributes #

Te permite seleccionar qué facets de búsqueda soportan la selección de múltiples opciones simultáneamente (como filtrar por los colores “Red” y “Blue” al mismo tiempo). Esto ofrece una experiencia de filtrado mucho más flexible y práctica.

Nota: Ahora puedes solicitar datos de categorías y páginas en tu Search Page del mismo modo que en Live search, ofreciéndote más información para interactuar con tus clientes. Para más información, puedes consultar aquí.

Personalización de facets #

• Clerk te permite diseñar los facets de tu Search Page desde el apartado de diseño y puedes mostrarlos haciendo referencia al campo design ID.

• El ID de diseño puede encontrarse en el backend de Clerk, en la columna izquierda de cada diseño en la página de vista general de diseños y en la esquina inferior izquierda tras entrar a editarlo.

Powerstep y exit intent #

Al igual que con Search, activa tu Powerstep de Clerk seleccionando “Yes” en el desplegable y, a continuación, elige el tipo de powerstep que deseas que aparezca (página o ventana emergente).

• Proporciona el nombre del Element para tu Powerstep, que se encuentra junto a data-template en el código de inserción dentro de tu Element de Powerstep, power-step-others-also-bought en este ejemplo.

• Sigue el mismo proceso anterior para habilitar tu Exit Intent e identificar y agregar el Exit Intent Element correspondiente.

Powerstep Filter Duplicates #

Al habilitar esto se evita que se recomienden productos duplicados en varios sliders dentro del Powerstep. Si un producto ya se muestra en un slider, Clerk.io lo excluirá automáticamente de los siguientes sliders en la misma página.

Recommendations #

También similar a Search, activa tus Product, Category y Cart Page Settings de Clerk eligiendo “Enabled” desde los desplegables correspondientes.

• Al igual que con las funcionalidades de Search, puedes encontrar el nombre del element junto a data-template en el código de inserción dentro de my.clerk.io > Recommendations > Elements.

  • En este ejemplo, hemos activado Product Page, Category Page y Cart Page settings, e incluido category-page-popular como nuestro elemento de Category Page, product-page-alternatives y product-page-others-also-bought en la Product Page, así como cart-others-also-bought en la Category Page.

Category Filter Duplicates #

Al activar esta opción se evita que se recomienden productos duplicados en varios sliders de tus páginas de categoría. Así, los clientes verán una mayor variedad de productos y no el mismo artículo varias veces en diferentes secciones.

Product Filter Duplicates #

Al habilitar esto, se evita que productos duplicados aparezcan como recomendados en múltiples sliders de tus páginas de detalle de producto. Así se mantienen las recomendaciones frescas y se maximizan las posibilidades de captar el interés del cliente con diferentes artículos.

Cart Filter Duplicates #

Al habilitar esto, se evitan productos duplicados recomendados en múltiples sliders en la página del carrito de compras. Es muy efectivo para ventas cruzadas, ya que garantiza una mayor variedad y atractivo de productos de última hora.

Después de todo, si un cliente ya decidió no comprar una tostadora verde neón en el primer slider, mostrársela tres veces más antes de pagar probablemente no lo hará cambiar de opinión, y podría hacer que dude de la cordura de tu tienda.

Registro de eventos (logging) #

Lo primero que debes hacer para cambiar los ajustes de registro es entrar en el backend de Magento2 y escoger Stores => Configuration => Clerk => Configuration:

Encuentra el desplegable llamado Logging Settings y establece el modo de registro que prefieras.

Finaliza haciendo clic en Save:

Los ajustes de Logging incluyen:

Elegir nivel de registro

• Only Errors: Registrará solo los errores que impiden el correcto funcionamiento del módulo.

• Error + Warn: También registrará advertencias que no detienen el módulo, pero pueden requerir atención.

• Error + Warn + Debug: Registra todo con lo que interactúa el módulo. No se debe habilitar esto en una tienda en vivo ya que ralentizará el sitio.

Elegir dónde registrar

• File: Guardará el registro en un archivo en el servidor de Magento2.

• my.clerk.io: Registrará todo en Developers->Logs en el backend de my.clerk.io.

Log File Link #

Muestra la ruta absoluta al archivo local de registro en tu servidor Magento (típicamente /var/log/clerk_log.log). Esto facilita a desarrolladores o administradores localizar e inspeccionar los archivos de registro para depurar el comportamiento de la extensión.

Actualización #

Si usas una versión anterior a la 3.0.0, actualizar romperá tus diseños, ya que se usará Clerk.js 2. Si usas una versión antigua, sigue esta guía en su lugar.

Importante: Recuerda hacer copias de seguridad de cualquier archivo modificado, ya que serán sobrescritos.

La actualización de la extensión de Magento 2 se realiza por línea de comandos.

Se hace siguiendo estos pasos:

1. Accede a tu servidor por línea de comandos.

2. Navega a tu carpeta webroot (normalmente " /var/www/your_domain/public_html")

3. Habilita Root Access escribiendo su y luego tu contraseña.

4. Escribe los siguientes comandos en orden:

   composer update clerk/magento2

   php bin/magento setup:upgrade

   php bin/magento setup:di:compile

5. Espera a que termine la extensión.

Tu Magento 2 ahora está actualizado a la última versión.

Desinstalación #

Igual que al instalar extensiones en Magento 2, la desinstalación debe hacerse por Command Line.

Simplemente escribe los siguientes comandos en orden para eliminarla:

1. php bin/magento setup:module:disable Clerk_Clerk

2. composer remove clerk/magento2