Integración

Configuración del Widget

Todas las opciones disponibles para personalizar el comportamiento y apariencia del buscador.

KoplyConfig

El widget se configura a través del objeto global window.KoplyConfig, que debe declararse antes de cargar el script de Koply. Los valores aquí definidos tienen prioridad sobre los configurados en el panel de Koply. 

<script>
  window.KoplyConfig = {
    apiKey:         'TU_API_KEY',          // requerido
    primaryColor:   '#1b60d9',             // opcional
    placeholder:    'Buscar productos...', // opcional
    locale:         'es',                  // opcional
    selector:       'input[type=search]',  // opcional
    resultsPerPage: 20,                    // opcional
  };
</script>
<script src="https://koply.eu/widget/koply.js" defer></script>

Referencia de opciones

Parámetro Tipo Por defecto Descripción
apiKey string — Requerido. API key del sitio. Encuéntrala en el panel en Embed code.
primaryColor string #1b60d9 Color principal del widget en formato hex. Se aplica a botones, checkboxes y precios.
placeholder string Buscar productos... Texto placeholder del campo de búsqueda dentro del widget.
locale string es Idioma de los textos de la interfaz. Valores: es, en, fr, de, pt.
selector string input[type=search] Selector CSS del campo de búsqueda al que se adjunta el widget. Solo se configura en el snippet — no está disponible desde el panel.
resultsPerPage number 20 Número de productos por página en los resultados. Máximo 50.

Cambiar el selector del campo de búsqueda

Por defecto el widget se adjunta al primer input[type=search] de la página. Si tu buscador usa un selector distinto, configura el parámetro selector: 

window.KoplyConfig = {
  apiKey:   'TU_API_KEY',
  selector: '#buscador-productos',  // ID específico
  // selector: '.mi-buscador',      // clase CSS
  // selector: 'input[name=q]',     // por atributo name
};

Personalización del color

El parámetro primaryColor controla el color de acento del widget: chips de sugerencias, checkboxes de filtros, precios y botones de acción. 

window.KoplyConfig = {
  apiKey:       'TU_API_KEY',
  primaryColor: '#e85d27',  // naranja de tu marca
};
Nota: El color debe estar en formato hexadecimal de 6 dígitos (ej: #e85d27). No se admiten nombres de color CSS ni formatos rgb().

CSS personalizado

Para personalizaciones visuales más avanzadas puedes inyectar CSS propio que se aplica sobre los estilos base del widget. Úsalo para ajustar bordes, radios, tipografía u otros detalles visuales específicos de tu marca.

El widget expone estas variables CSS que puedes sobreescribir:

Variable Descripción Por defecto
--es-primary Color principal (botones, checkboxes, precios) #1b60d9
--es-radius Radio de bordes de las tarjetas de producto 8px
--es-font Familia tipográfica del widget hereda del sitio
--es-overlay-bg Color del fondo semitransparente del overlay rgba(0,0,0,0.4)

Ejemplo de personalización para una tienda con estilo verde y bordes marcados:

<style>
  :root {
    --es-primary: #00a650;
    --es-radius:  4px;
  }
  .es-card {
    border: 2px solid #00a650;
  }
  .es-chip {
    border-radius: 4px;
  }
</style>
Todos los elementos del widget usan el prefijo de clase .es- para evitar conflictos con los estilos existentes de tu web.

Idiomas disponibles

El widget incluye traducciones completas para los siguientes idiomas:

Eventos JavaScript

El widget expone eventos nativos del navegador que puedes escuchar para conectar lógica personalizada — por ejemplo, actualizar el mini-cart o registrar conversiones en Analytics.

Evento Cuándo se dispara Datos disponibles
koply.cart.add El usuario hace clic en "Añadir al carrito" entity_id, qty
koply.cart.added El producto se ha añadido correctamente al carrito — 
window.addEventListener('koply.cart.add', function (e) {
  console.log('Producto:', e.detail.entity_id, 'Qty:', e.detail.qty);
});

window.addEventListener('koply.cart.added', function () {
  // Actualiza el mini-cart de tu tema
});
Quick Start Magento 2