Integración

Magento 2

Módulo oficial de Koply para Magento 2. Instalación en minutos, sin tocar código.

Requisitos

  • Magento 2.4.x
  • PHP 8.1 o superior
  • Una cuenta activa en koply.eu con un sitio configurado

1. Instala el módulo

La forma recomendada es vía Composer desde el directorio raíz de tu instalación de Magento:

composer require koply/magento2-search
php bin/magento module:enable Koply_Search
php bin/magento setup:upgrade
php bin/magento cache:clean

Instalación manual

Si no puedes usar Composer, descarga el ZIP desde GitHub, extrae el contenido en app/code/Koply/Search/ y ejecuta:

php bin/magento module:enable Koply_Search
php bin/magento setup:upgrade
php bin/magento cache:clean

2. Configura el módulo

Una vez instalado, ve a Stores → Configuration → Koply → Search Widget en el panel de administración de Magento.

Campo Descripción
Enable Activa o desactiva el widget en el frontend. Ponlo en Yes.
API Key Tu clave de API del sitio. La encuentras en el panel de Koply bajo Sitios → Embed code.

Guarda la configuración y limpia la caché:

php bin/magento cache:flush
El resto de la configuración se gestiona desde el panel de Koply — colores, placeholder, idioma y selector CSS. No necesitas modificar ningún archivo de Magento.

3. Cómo funciona

El módulo inyecta automáticamente el script del widget de Koply antes del cierre de </body> en todas las páginas del frontend. No requiere modificar ninguna plantilla.

El botón Añadir al carrito que aparece en los resultados de búsqueda funciona de forma nativa con Magento 2 — el módulo gestiona la petición internamente usando el endpoint estándar de Magento. No necesitas implementar nada adicional.

4. Verifica la integración

Abre el frontend de tu tienda y escribe al menos 2 caracteres en el campo de búsqueda. El widget de Koply debe activarse y mostrar resultados en tiempo real.

Para confirmar que el módulo está activo, puedes ejecutar:

php bin/magento module:status Koply_Search

La salida debe mostrar Module is enabled.

Dominio en el panel de Koply
El dominio configurado en tu sitio de Koply debe coincidir exactamente con el dominio desde el que se carga el widget. Una discrepancia bloqueará todas las peticiones de búsqueda.

Eventos JavaScript

El módulo expone eventos nativos del navegador para que puedas conectar lógica personalizada si tu tema lo requiere.

Evento Cuándo se dispara Datos disponibles
koply.cart.add El usuario hace clic en "Añadir al carrito" en el widget entity_id, qty
koply.cart.added El producto se ha añadido correctamente al carrito —

Ejemplo de uso:

window.addEventListener('koply.cart.added', function () {
    // Actualiza el mini-cart de tu tema si es necesario
    document.dispatchEvent(new CustomEvent('reload.customer.section.data'));
});
Configuración del Widget ¿Problemas? Contacta soporte