Ir al contenido
Instalar la app
Español

Eventos

Los cinco eventos que emite la app en la tienda online, cada uno con un ejemplo práctico.

La app emite estos eventos en document, así que escúchalos con document.addEventListener. Coloca el código en un recurso del tema o en theme.liquid, encima de </body>.

EventodetailSe emite cuando
gpoRenderCompleted{ form, product }Las opciones han terminado de renderizarse
gpoElementChanged{}El cliente ha cambiado una opción
gpoProductPriceUpdated{}Se ha recalculado el precio mostrado
gpoValidated{ success }Se ha ejecutado la validación al agregar al carrito
gpoAddedToCart{}El artículo y sus complementos han llegado al carrito

gpoRenderCompleted

Se emite en cuanto los campos de opción existen en el DOM. Este es el evento sobre el que debes construir. La app renderiza de forma asíncrona, así que el código que se ejecuta en DOMContentLoaded se ejecuta antes de que existan las opciones y no encuentra nada.

detail contiene form, el formulario del producto en el que se renderizaron las opciones, y product, el producto para el que se renderizaron.

document.addEventListener('gpoRenderCompleted', function (event) {
const { form, product } = event.detail;
if (!form) return; // ningún conjunto de opciones se aplica a este producto
// Ya puedes consultar los campos de opción con seguridad
form.querySelectorAll('.gpo-form__group').forEach(function (group) {
group.classList.add('my-theme-option');
});
});

Se vuelve a emitir cada vez que las opciones se renderizan de nuevo: tras un cambio de variante en los temas que vuelven a renderizar el producto, o después de llamar a GPOConfigs.initialize(). Escribe el controlador de forma que ejecutarlo dos veces no cause problemas.

gpoElementChanged

Se emite cada vez que el cliente cambia una opción: al escribir en un campo, elegir una muestra o marcar una casilla.

document.addEventListener('gpoElementChanged', function () {
const engraving = document.querySelector('[name="properties[Engraving text]"]');
const note = document.querySelector('.my-engraving-note');
if (!engraving || !note) return;
note.hidden = engraving.value.trim() === '';
});

Se emite con cada pulsación de tecla en un campo de texto, así que aplica un debounce a cualquier cosa costosa, como una solicitud de red o un rediseño pesado.

gpoProductPriceUpdated

Se emite después de que la app haya reescrito el precio mostrado para incluir las opciones que eligió el cliente. Úsalo para mantener sincronizada tu propia visualización del precio: una barra fija, un bloque de resumen, una estimación de pago a plazos.

document.addEventListener('gpoProductPriceUpdated', function () {
const main = document.querySelector('[data-gpo-product-unit-price]');
const sticky = document.querySelector('.my-sticky-bar .price');
if (main && sticky) sticky.textContent = main.textContent;
});

El precio que se muestra en la página es una vista previa. Lo que realmente se le cobra al cliente lo aplica Shopify en la pantalla de pago, así que nunca trates esta cifra como el importe final. Consulta Cómo se aplican los precios.

gpoValidated

Se emite cuando el cliente intenta agregar al carrito y la app ha comprobado las opciones. detail.success es false cuando algo está mal: una opción obligatoria vacía, un límite de caracteres superado, muy pocas selecciones.

document.addEventListener('gpoValidated', function (event) {
if (event.detail.success) return;
// Se bloqueó la acción de agregar al carrito
if (window.analytics) {
window.analytics.track('Option validation failed', {
product: window.GPOConfigs?.product?.handle
});
}
});

La app ya se desplaza hasta el primer error cuando Desplazamiento automático al primer mensaje de error está activado, así que no necesitas hacerlo tú. Consulta Comportamiento del widget.

gpoAddedToCart

Se emite después de que se hayan agregado el artículo y los productos complementarios. En este punto el carrito ha cambiado de verdad, lo que lo convierte en el lugar adecuado para abrir el carrito y para las analíticas.

document.addEventListener('gpoAddedToCart', function () {
fetch(window.Shopify.routes.root + 'cart.js')
.then(function (res) { return res.json(); })
.then(function (cart) {
document.querySelector('.my-cart-count').textContent = cart.item_count;
});
});

Un complemento respaldado por un producto es su propia línea del carrito, así que una sola acción de agregar al carrito puede agregar varias líneas. Vuelve a leer el carrito en lugar de suponer que se agregó un solo artículo. Consulta Combinar el producto principal y los complementos.

Notas

  • Los cinco necesitan la inserción de aplicación activada. Sin ella, la app nunca se ejecuta y no se emite nada.
  • Los eventos no contienen datos de clientes más allá de los que ya están en la página. Lee window.GPOConfigs para obtener el producto, el carrito y el cliente.
  • El mantenimiento del código que agregues aquí es responsabilidad tuya, y es lo primero que debes revisar cuando la tienda online no funciona bien tras una actualización del tema o de la app.

¿Te ha sido útil?

Informar de un problema