Configuración de Commerce

Beaconry engancha los action hooks reales de tu tienda y dispara el embudo de la tienda del lado del servidor: vistas de producto, cambios en el carrito, checkout, compra y reembolso, cada evento llevando el array completo GA4 items[] y el bloque de catálogo Meta content_* para que los Dynamic Product Ads coincidan sin configuración extra. Hoy hay tres plataformas disponibles: WooCommerce, Easy Digital Downloads y SureCart. Activa el plugin, pulsa el interruptor en la pestaña Commerce, listo. No hay ningún snippet de JavaScript que pegar en una plantilla.

Las tres plataformas de un vistazo

Cada plataforma recibe un adaptador dedicado que solo se registra cuando su plugin host está cargado y has activado su interruptor. Una instalación con solo WooCommerce nunca lleva rutas de código de EDD o SureCart. Cuánto del embudo expone una plataforma depende por completo de qué hooks dispara esa plataforma del lado del servidor, y las tres difieren mucho aquí.

La forma de cada evento es idéntica en las tres: un array GA4 items[] (item_id, item_name, item_brand, item_category, item_variant, price, quantity) y un bloque de contenido Meta CAPI (content_ids[], content_type, content_name, content_category, num_items). Esa única forma canónica es lo que permite que una sola compra se reparta en diez canales y siga coincidiendo con el catálogo de productos de cada plataforma. La moneda viene directamente de la tienda (moneda de la tienda WooCommerce, moneda de la tienda EDD, la moneda de cada pedido SureCart), y Multi-currency la normaliza automáticamente en cuanto lo activas.

Activar el seguimiento de commerce

La pestaña Commerce solo aparece en el menú de Beaconry cuando hay un plugin de tienda compatible activo, así que nunca te quedas mirando una pestaña vacía. Abre wp-admin, Beaconry, Commerce. Cada plataforma detectada tiene su propia tarjeta con un único interruptor maestro y una lista desplegable "¿Qué eventos se rastrean?". Pulsa el interruptor, guarda, y esa plataforma empieza a disparar de inmediato. Guardar en esta pestaña solo escribe los tres interruptores de commerce, tus ajustes de la pestaña Forms nunca se tocan.

Los service pills en la parte superior de la pestaña muestran cada plataforma activa como encendida o apagada de un vistazo y te desplazan hasta su tarjeta. Esa es toda la configuración. Los campos de customer-matching (email, teléfono, nombre, ciudad, código postal) se extraen del pedido automáticamente y se hashean con SHA-256 por canal antes de que nada salga de tu servidor, así obtienes buena calidad de coincidencia sin trabajo extra.

WooCommerce: el embudo completo de 10 eventos

WooCommerce es la integración más profunda porque dispara el conjunto más rico de hooks del lado del servidor. Los diez eventos estándar de commerce están cubiertos:

1. view_item: un visitante abre una página de producto. El evento clave para la coincidencia de catálogo de Meta Dynamic Product Ads.
2. view_item_list: un visitante abre la tienda, una categoría o un archivo de tag. Limitado a 24 productos para que la vista de un archivo grande siga siendo un payload acotado.
3. view_cart: un visitante abre la página del carrito.
4. add_to_cart: un visitante añade un producto. Cubre las tres rutas de añadido: recarga clásica de página, botones inline AJAX en los archivos y el add-to-cart del block / Store-API.
5. remove_from_cart: un visitante elimina una línea de pedido.
6. search: un visitante busca en la tienda, incluyendo la URL de resultado de búsqueda de producto independiente que no es una página de tienda o categoría.
7. begin_checkout: un visitante entra en el checkout. Dispara tanto en el checkout de shortcode clásico como en el bloque Checkout.
8. add_payment_info: el pedido se realiza y se confirma un método de pago. Dispara tanto en el procesamiento de pedidos clásico como en el de Store-API (block).
9. purchase: el pedido se recibe, con todas las líneas de pedido, envío, impuestos y códigos de cupón.
10. refund: el pedido se reembolsa. Se envía como un evento de valor negativo para que los informes calculen el neto correctamente (ver "Reembolsos" más abajo).

Checkout clásico y de bloque

Esta es la parte que la mayoría de configuraciones del lado del servidor hace mal, así que vale la pena ser explícito. El checkout basado en bloque no tiene ningún hook del lado del servidor de "formulario de checkout renderizado", así que una integración ingenua nunca dispara begin_checkout en los checkouts de bloque, en silencio. Beaconry maneja el checkout de forma agnóstica a la ruta de renderizado: se basa en is_checkout() en template_redirect (una coincidencia de Page-ID, no una URL ni una ruta de renderizado) para que el shortcode clásico, el bloque Checkout de Gutenberg y los checkouts de page builder disparen todos un begin_checkout. Los hooks clásicos woocommerce_before_checkout_form y el hook oficial de bloque woocommerce_blocks_checkout_enqueue_data siguen conectados como doble seguridad, y un guard por petición reduce el que dispare primero a un único dispatch. La misma cobertura doble se aplica a add_payment_info, que escucha tanto en woocommerce_checkout_order_processed (clásico) como en woocommerce_store_api_checkout_order_processed (block).

Una consecuencia de los contextos de bloque y AJAX: esos hooks disparan dentro de una petición REST o admin-ajax, donde la URL de la petición es el endpoint, no la página en la que estaba el cliente. Beaconry detecta el contexto asíncrono mediante flags de la API de WordPress (REST_REQUEST, wp_doing_ajax()) y resuelve la URL de la página de cara al cliente a partir del referer o del permalink configurado de la página de checkout. Nunca parsea ni hace slug-match de URLs, así que una página de carrito o checkout renombrada no puede romper el seguimiento.

El event_id por pedido

Los eventos de compra usan un event_id determinista derivado del pedido, bcnr_purchase_<order_id>. Una recarga de la página de agradecimiento vuelve a disparar el hook woocommerce_thankyou de WooCommerce, pero el id estable más un marcador de order-meta hacen que la compra solo se cuente una vez. Ese mismo id es también lo que hace funcionar la deduplicación del Modo Híbrido: si además ejecutas un pixel de navegador, Beaconry pasa el event_id idéntico al evento Purchase del lado del navegador para que el proveedor deduplique las copias de navegador y servidor por su lado. Los eventos de vista que no tienen una clave única natural (view_item_list, view_cart, begin_checkout) usan un id determinista con ventana para que un prefetch o una doble petición por redirección colapse en una conversión, mientras que una vista repetida genuina minutos después sigue contando.

Coincidencia de catálogo: items[] y content_*

Cada evento de WooCommerce lleva ambas representaciones de los productos implicados. item_id y content_ids[] prefieren el SKU del producto y recurren al ID de producto de WooCommerce, así que encajan con tus feeds de Google Merchant Center y Meta Catalog. item_brand se lee del atributo pa_brand o de una taxonomía product_brand, item_category de la primera categoría de producto asignada e item_variant de los atributos de variación en productos variables. El bloque Meta establece content_type en product_group cuando hay más de un producto presente y en product en caso contrario. Nada de esto necesita configuración, se deriva de tus datos de producto existentes.

Easy Digital Downloads: 8 eventos

EDD es el estándar para bienes digitales (plugins, themes, eBooks, música) y muchos clientes de Beaconry lo usan en lugar de WooCommerce porque es más ligero para ventas puramente digitales. EDD dispara hooks del lado del servidor para la mayor parte del embudo, así que Beaconry rastrea ocho eventos:

• view_item: un visitante abre una página de download (producto).
• view_item_list: un visitante abre el archivo de la tienda, una categoría de download o un tag. Capturado en el archivo CPT nativo, el shortcode [downloads] y el bloque Gutenberg edd/downloads.
• view_cart: un visitante abre el checkout con artículos en el carrito.
• add_to_cart: un visitante añade un download al carrito.
• remove_from_cart: un visitante elimina un download.
• begin_checkout: un visitante entra en el checkout de EDD.
• purchase: un pago se completa, con todos los downloads, impuestos y totales.
• refund: un pago se reembolsa, enviado como un evento de valor negativo.

Dos eventos de la lista de WooCommerce están ausentes de forma intencionada porque EDD no los expone del lado del servidor. No hay evento search (EDD no tiene ningún hook de búsqueda de tienda al que Beaconry pueda engancharse) ni evento add_payment_info (el paso de método de pago de EDD lo renderiza el theme y no se expone como una action). Los ocho eventos de arriba son todo lo que EDD trae de fábrica.

Igual que con WooCommerce, los eventos de vista y checkout son agnósticos a la ruta de renderizado. Se basan en is_singular('download') y edd_is_checkout() en template_redirect en lugar de en los antiguos hooks de plantilla basados en the_content, así que disparan correctamente incluso cuando un page builder (Elementor Theme Builder, Divi, Bricks) renderiza la plantilla de download individual o de checkout y se salta the_content. Los eventos de compra deduplican con un id estable por pago, bcnr_edd_purchase_<payment_id>, así que una recarga de la página de agradecimiento nunca cuenta doble.

SureCart: compra en servidor más el puente del navegador

SureCart es el actor de commerce más nuevo, de estilo SaaS, fuerte en suscripciones y cada vez más popular entre las tiendas con mentalidad de performance marketing que son el público principal de Beaconry. Su arquitectura necesita un enfoque distinto. La UI de carrito y checkout de SureCart es un web component de JavaScript (sc-line-item-list y compañía) que no emite ninguna action de PHP para los eventos del carrito, así que no hay nada a lo que un hook del lado del servidor pueda engancharse para add_to_cart, view_cart, begin_checkout y el resto.

Beaconry divide la cobertura para ajustarse a esta realidad:

• Del lado del servidor, autoritativo: el adaptador de PHP dispara purchase en la action surecart/checkout_confirmed y refund en el evento del modelo de reembolso de SureCart. Estas son las conversiones que nunca deben perderse, y engancharlas en PHP significa que se cuentan incluso para pedidos que nunca tocan la UI del carrito del navegador, como pedidos por email o de cobro manual. La compra deduplica con un id estable por pedido, bcnr_sc_purchase_<order_id>.
• Puente del navegador, para el embudo del carrito: los eventos de JavaScript del embudo superior que SureCart despacha en el navegador (vista de producto, vista de lista, add-to-cart, remove, vista de carrito, begin checkout, info de pago y envío, búsqueda) los captura el puente de SureCart dentro del motor de navegador de Beaconry y los redirige por exactamente el mismo endpoint REST de mismo origen y el mismo forwarder del lado del servidor. Así que esos eventos siguen rastreándose, y siguen siendo del lado del servidor desde el punto de vista del proveedor, simplemente entran en el pipeline desde el navegador en lugar de desde un hook de PHP.

El resultado práctico: SureCart obtiene el embudo completo, pero los dos eventos que deciden los ingresos, purchase y refund, tienen una garantía dura del lado del servidor independiente de cualquier JavaScript del navegador, mientras que los eventos del embudo del carrito viajan en el puente. Los importes se manejan correctamente para monedas de cero decimales (JPY, KRW y el resto), donde el importe de SureCart ya está en unidades mayores en lugar de céntimos.

Reembolsos: solo GA4, por diseño

El enrutamiento de reembolsos es el único punto en el que el seguimiento de commerce tiene que tener una opinión, y Beaconry la tiene. Cuando un pedido se reembolsa en cualquiera de las tres plataformas, el reembolso se envía solo a GA4. Cada canal publicitario se omite deliberadamente. La razón es simple y vale la pena entenderla:

• GA4 tiene un evento refund real que calcula el neto de los ingresos reembolsados contra la compra original, así que tu informe de ingresos de GA4 se mantiene preciso sin una hoja de cálculo. Beaconry envía el reembolso allí como un evento de valor negativo vinculado al mismo id de transacción.
• Ningún canal publicitario tiene un evento de reembolso verdadero. Meta CAPI, TikTok, Pinterest, Snapchat, Reddit y el resto, o bien no tienen ningún evento de reembolso, o solo un evento personalizado que es un contador muerto, invisible para Smart Bidding y nunca compensado contra la conversión. Peor aún, en algunos canales (Snapchat, por ejemplo) un evento de reembolso personalizado forzado colisionaría con el slot reservado para las conversiones de lead, contaminando tu informe de conversiones. Enviar un reembolso falso a una plataforma publicitaria añade ruido y cero valor de optimización, así que Beaconry no lo hace.

Esta división se aplica de forma centralizada en el forwarder, no por plataforma, así que los tres adaptadores de commerce obtienen un comportamiento de reembolso idéntico y un canal futuro hereda la regla automáticamente. Si necesitas que los reembolsos se reflejen en el informe de una plataforma publicitaria, eso es una exportación manual contra la propia API de gestión de pedidos o de ajuste de conversiones offline de la plataforma, una superficie distinta de la Conversions API que Beaconry controla.

Cobertura de eventos por canal

No todos los eventos del embudo se mapean limpiamente en el vocabulario de eventos estándar de cada canal publicitario. Beaconry solo envía un evento a un canal cuando ese canal tiene un evento estándar significativo para él, de lo contrario se omite en el forwarder para que no obtengas conteos duplicados ni eventos personalizados basura que inflen el gestor de conversiones de un canal. GA4 recibe el embudo completo. La tabla de abajo muestra dónde aterriza cada evento de WooCommerce o EDD (los eventos del lado del servidor de SureCart son purchase y refund; sus eventos de carrito puenteados siguen las mismas reglas por canal que las filas de abajo).

Por qué "Omitido" aparece tan a menudo en las filas del embudo superior y de reembolso: la mayoría de los canales publicitarios mapean view_item_list y view_cart en el mismo evento de estilo ViewContent que view_item, así que enviar los tres duplicaría o triplicaría una sola vista de página en el informe de ese canal sin darle a Smart Bidding ninguna señal nueva. Esos canales optimizan sobre señales de detalle de producto y de conversión (ViewContent, AddToCart, Purchase), no sobre vistas de lista o de carrito, así que Beaconry envía el significativo y omite los duplicados. remove_from_cart y refund no tienen ningún slot estándar en esos canales. Pinterest es la excepción que conserva view_item_list, porque tiene un evento view_category propio. El vocabulario estándar de Reddit no tiene ningún evento de etapa de checkout, así que begin_checkout y add_payment_info aterrizan allí como eventos personalizados en lugar de conversiones estándar, mientras que Snapchat tiene slots nativos START_CHECKOUT y ADD_BILLING.

Los cuatro canales de slot de conversión (Google Ads, Microsoft Ads, LinkedIn, X Ads) no se muestran como columnas porque funcionan de forma distinta: cada uno solo dispara los eventos que hayas mapeado explícitamente a una conversion action, goal, rule o slot en la configuración de ese canal. Mapea purchase a una conversion action de Google Ads y una compra dispara allí; deja un evento del embudo sin mapear y simplemente no se despacha a ese canal. Reciben el feed completo del embudo, tu configuración de slots decide qué eventos se convierten en conversiones. Consulta las guías por canal en Configuración de canales para el mapeo de slots en cada uno.

Consentimiento y tráfico de admin

Los eventos de commerce pasan por la misma puerta central de consentimiento que cualquier otro evento de Beaconry: sin el consentimiento del visitante almacenado en la cookie nl_pref, no se despacha nada. Como una compra o un reembolso es una action del lado del servidor ya completada, el consentimiento se aplica una vez en el dispatcher en lugar de volver a comprobarse en cada hook. Los admins con sesión iniciada quedan excluidos del seguimiento de front-end por defecto, con una excepción deliberada: cuando un admin marca un pedido de SureCart como pagado o procesa un reembolso desde el panel, esa conversión pertenece al cliente que compró, no al admin que pulsa el botón, así que esos eventos de servidor específicos saltan la puerta de admin y se cuentan igualmente.

Solución de problemas

• "begin_checkout nunca dispara en mi block checkout": confirma que el interruptor de WooCommerce está activado en Beaconry, Commerce, y que no tienes la sesión iniciada como admin (el seguimiento de front-end omite a los admins por defecto). El block checkout está cubierto por is_checkout() en template_redirect, así que una página de checkout renombrada no es la causa. Observa cómo llega el evento en la vista en tiempo real de GA4 o en el Live Dashboard.
• "Faltan mis eventos de SureCart add-to-cart": esos viajan en el puente del navegador, no en un hook de PHP, así que solo disparan después de que el visitante acepte el consentimiento (el puente está sujeto a consentimiento como todos los eventos de navegador). purchase y refund son del lado del servidor e independientes del puente, así que si las compras llegan pero los eventos de carrito no, comprueba que se esté aceptando el banner de consentimiento.
• "EDD no muestra eventos de search ni de payment-info": es lo esperado. EDD no expone hooks del lado del servidor para ninguno de los dos, así que esos dos eventos no forman parte del embudo de EDD. Los otros ocho sí.
• "Los reembolsos no aparecen en Meta / Google Ads": también es lo esperado, y por diseño. Los reembolsos se enrutan solo a GA4 porque ningún canal publicitario tiene un evento de reembolso real. Comprueba el evento refund de GA4, donde el valor negativo se compensa contra la compra.
• "Una recarga de la página de agradecimiento contó la compra dos veces": no debería, el event_id por pedido más un marcador de order-meta lo evitan. Si ves un duplicado genuino, verifica que no estés disparando además una segunda compra desde un pixel de navegador separado sin pasarle el event_id de Beaconry (el Modo Híbrido lo conecta por ti).