¿Te gustaría saber qué campañas están generando donaciones? El complemento Charitable se conecta a Google Analytics 4, captura cada evento de donación y te muestra exactamente de dónde provienen tus donantes. Rastrea conversiones tanto del lado del navegador como del lado del servidor, para que no pierdas donaciones de redirecciones de PayPal, pagos confirmados por webhook o donaciones sin conexión confirmadas por el administrador.

Esta guía te guiará a través de los pasos para conectar tu sitio Charitable a GA4, habilitar el seguimiento del lado del servidor, configurar opciones de privacidad y revisar los datos que Charitable captura para cada donación.

Nota: 
Requisitos: Charitable Pro 1.8.13+
El complemento de Google Analytics requiere el plan Pro o superior.

Antes de empezar, asegúrate de que Charitable Pro esté instalado y activado en tu sitio. También necesitarás una propiedad de Google Analytics 4 con al menos un flujo de datos configurado para tu sitio web.

En esta guía

• Configuración del complemento de Google Analytics
• Habilitar el seguimiento del lado del servidor
• Configuración del consentimiento y la privacidad
• Exclusión del tráfico interno
• Prueba de tu conexión
• Revisión de los datos de origen de las donaciones en WordPress
• Comprensión de los eventos que rastrea Charitable
• Visualización de tus datos en GA4
• Prueba de la función
• Solución de problemas
• Filtros
• Acciones
• Claves meta de donación
• Nombres de cookies
• Claves de opciones de configuración
• Constantes
• Recetas comunes
• Orden de disparo de ganchos
• Preguntas frecuentes

Configuración del complemento de Google Analytics

Una vez que hayas instalado y activado el complemento, la configuración de GA4 se agregará al panel de configuración avanzada de Charitable. Para abrirlas, ve a Charitable » Configuración » Avanzado en tu administrador de WordPress.

Necesitarás tu ID de medición de GA4, que comienza con G- seguido de una cadena de letras y números. Para encontrarlo, inicia sesión en tu cuenta de Google Analytics, abre Administrar » Flujos de datos y selecciona tu flujo web. El ID de medición se muestra en la esquina superior derecha de la página de detalles del flujo.

De vuelta en tu administrador de WordPress, pega el ID de medición en el campo Google Analytics y luego haz clic en Guardar cambios en la parte inferior de la página.

Nota: El complemento valida que el ID de medición comience con G-. Si pegas accidentalmente un ID de contenedor de Google Tag Manager (que comienza con GTM-) o un ID de propiedad de Universal Analytics heredado (UA-), el seguimiento no funcionará. El formato actual de GA4 es el único compatible.

Habilitar el seguimiento del lado del servidor

El seguimiento del lado del navegador con gtag.js funciona bien cuando los donantes completan el pago en tu sitio y llegan a la página de recibo de donación. Pero muchas donaciones finalizan en lugares que el navegador no puede ver: una redirección de PayPal Standard donde el donante cierra la pestaña, un webhook de Stripe que confirma el pago horas después, o un administrador que marca manualmente una donación sin conexión como pagada. Sin el seguimiento del lado del servidor, esas donaciones nunca llegan a Google Analytics.

El seguimiento del lado del servidor de Charitable envía un evento de compra confirmado a GA4 en el momento en que el estado de una donación cambia a Pagado, independientemente de si el navegador del donante está involucrado. La misma ruta también dispara un evento de reembolso cuando se reembolsa una donación.

Para habilitar el seguimiento del lado del servidor, necesitarás un secreto de API del Protocolo de Medición de tu propiedad de GA4. Para crear uno, inicia sesión en Google Analytics, abre Administrar » Flujos de datos, selecciona tu flujo web, desplázate hacia abajo hasta Secretos de la API del Protocolo de Medición y haz clic en Crear. Dale un apodo al secreto para que puedas identificarlo más tarde.

Una vez que tengas el secreto, copia su valor, regresa a Charitable » Configuración » Avanzado y pégalo en el campo Secreto de la API del Protocolo de Medición de GA4. Guarda tus cambios.

Nota: El secreto de la API es opcional. Si lo dejas en blanco, Charitable seguirá rastreando las donaciones en el sitio a través del navegador. La ruta del lado del servidor solo se activa cuando se configuran tanto el ID de medición como el secreto de la API.

El seguimiento del lado del servidor y del lado del navegador comparten un indicador de idempotencia, por lo que una donación que se completa en el sitio y se confirma por webhook solo disparará un evento de compra en GA4, nunca dos. La primera ruta que se active gana.

Configuración del consentimiento y la privacidad

El complemento incluye soporte completo para el Modo de Consentimiento de Google v2, que es obligatorio para el tráfico del Espacio Económico Europeo según las reglas de aplicación de Google de marzo de 2024. Sin él, los donantes que deniegan el consentimiento de análisis desaparecen por completo de GA4. Con él, GA4 aún recibe conversiones modeladas y pings sin cookies.

El estado del consentimiento se envía en el encabezado de la página, antes de que se cargue gtag.js, con las cuatro señales requeridas: analytics_storage, ad_storage, ad_user_data y ad_personalization. Los valores provienen de la plataforma de gestión de consentimiento que tengas instalada.

Configuración de Integración de Consentimiento

En el panel de configuración avanzada, verás una casilla de verificación de Integración de Consentimiento debajo del campo del secreto de la API. Esta configuración controla cómo el complemento se comunica con tu CMP a través del marco de la API de Consentimiento de WP, que es compatible con Cookiebot, CookieYes, Complianz, Iubenda, OneTrust y la mayoría de los otros complementos de consentimiento importantes.

• Habilitado (predeterminado): el complemento verifica wp_has_consent('statistics') en el momento de la donación y solo dispara eventos del lado del servidor para los donantes que han otorgado consentimiento de análisis. Elige esta opción si tienes una CMP instalada y deseas que los eventos del lado del servidor respeten el consentimiento del donante.
• Deshabilitado: el complemento ignora el estado de la API de Consentimiento de WP y dispara eventos del lado del servidor para cada donación completada. Elige esta opción solo si no tienes una CMP, o si tu equipo legal ha confirmado que los datos del donante se pueden enviar a Google sin consentimiento de análisis.

El estado de consentimiento se captura en el momento en que se crea la donación y se almacena en el registro de la donación. Eso significa que un donante que más tarde cambia de opinión en tu CMP no bloquea retroactivamente los eventos de las donaciones que ya ha realizado: la instantánea en el momento de la donación es la autoridad para esa donación.

Anonimización de IP

Las direcciones IP de los donantes siempre se anonimizan antes de enviarse a Google. Charitable trunca las direcciones IPv4 a /24 (el último octeto se pone a cero) y las direcciones IPv6 a /48 (los últimos 80 bits se ponen a cero) antes de pasarlas a GA4 como el parámetro ip_override.

El resultado: Google puede geolocalizar a los donantes a nivel de país y región – útil para la atribución de recaudación de fondos – pero nunca puede ver la IP exacta de un donante. La IP completa tampoco se almacena nunca en tu base de datos de WordPress.

Exclusión del tráfico interno

Si tu equipo inicia sesión para probar campañas o gestionar donaciones, probablemente no querrás que sus navegaciones aparezcan en GA4 junto con el tráfico real de los donantes. El campo Excluir seguimiento para roles te permite omitir el seguimiento por completo para los usuarios conectados en roles específicos.

Desde la configuración Avanzada, busca Excluir seguimiento para roles y marca las casillas de los roles que quieras excluir. Las opciones comunes son Administrador y Editor para un equipo pequeño, o solo Administrador si quieres que el personal de recaudación de fondos sea rastreado. Guarda tus cambios.

Para los usuarios excluidos, el complemento no cargará gtag.js en el frontend y no disparará ningún evento. Los visitantes desconectados y los usuarios en roles no seleccionados se rastrean normalmente.

Prueba de tu conexión

La mayor fuente de confusión con cualquier integración de análisis es "¿lo he configurado correctamente?". El complemento incluye una prueba de un clic que dispara un evento real a GA4 con el modo de depuración habilitado, y luego informa el resultado en línea.

Desde Charitable » Configuración » Avanzado, desplázate hasta la sección Probar conexión GA4 y haz clic en Enviar evento de prueba a GA4.

El botón hace dos cosas en secuencia. Primero, envía tu carga útil al punto final de depuración de GA4, que valida la estructura y rechaza los ID de medición o secretos de API no válidos con un error descriptivo. Segundo, envía el mismo evento al punto final en vivo de GA4 con debug_mode activado, por lo que el evento aparece en GA4 » Admin » DebugView en unos segundos.

Si la prueba tiene éxito, verás una marca de verificación verde con un mensaje de confirmación que nombra el evento de prueba (charitable_test_event). Si falla, el mensaje te dirá por qué: las causas más comunes son un secreto de API no válido, un error tipográfico en el ID de medición o un problema de conectividad de red entre tu servidor y Google.

El evento de prueba es inofensivo. Utiliza un ID de cliente sintético para que no aparezca junto con los datos reales de los donantes en tus informes estándar.

Revisión de los datos de origen de las donaciones en WordPress

Cada donación en tu panel de administración de Charitable muestra un panel de Google Analytics en la columna de la derecha de la pantalla de edición de la donación. El panel solo aparece cuando hay datos capturados para esa donación, por lo que las donaciones antiguas de antes de que se instalara el complemento no lo mostrarán.

El panel agrupa los datos capturados en cuatro secciones:

• Fuente (UTM) – muestra los valores utm_source, utm_medium, utm_campaign, utm_term, utm_content, y utm_id de la URL desde la que el donante llegó a tu sitio. Solo se muestran los campos con valores capturados.
• Sesión GA4 – muestra el ID de cliente y el ID de sesión GA4 del donante, analizados a partir de la cookie _ga en el momento de la donación. Estos te permiten cotejar la donación en los informes de GA4 si necesitas investigar una transacción específica.
• Consentimiento al insertar – muestra el estado de la API de Consentimiento de WP del donante para las categorías de estadísticas y marketing en el momento en que donó. Útil para auditorías de cumplimiento.
• Eventos GA4 disparados – muestra la marca de tiempo cuando los eventos purchase y (si corresponde) de refund se enviaron a GA4. Si una donación no tiene una marca de tiempo de purchase, significa que el evento aún no se ha enviado (aún pendiente) o fue suprimido por tu configuración de consentimiento o exclusión de roles.

El panel se carga colapsado por defecto para mantener la pantalla de edición de donaciones limpia. Haz clic en la barra de título de Google Analytics para expandirlo. WordPress recuerda tu preferencia por usuario.

Etiquetado UTM de tus campañas

Para que la sección Fuente (UTM) capture datos, el donante debe llegar a tu sitio a través de una URL que contenga parámetros UTM. Una URL de campaña típica podría verse así:

https://example.org/donate/?utm_source=email&utm_medium=newsletter&utm_campaign=spring-2026

Enviarías ese enlace en tu correo electrónico de recaudación de fondos en lugar de la URL desnuda de la página de donación. Cuando el donante hace clic, Charitable guarda esos valores UTM en una cookie de origen que dura 30 días. Cada vez que dona dentro de esa ventana, los valores UTM se adjuntan al registro de donación y se reenvían a GA4 como los parámetros de evento source, medium, y campaign.

Por defecto, el complemento utiliza la atribución de último contacto: si el donante visita con un conjunto de UTM, y luego visita más tarde con un conjunto diferente, el conjunto más reciente prevalece. Los desarrolladores pueden cambiar a la atribución de primer contacto con el filtro charitable_google_analytics_utm_first_touch.

Comprensión de los eventos que rastrea Charitable

Charitable dispara los siguientes eventos GA4 en diferentes puntos del ciclo de vida de la donación. Todos ellos aparecen automáticamente en tus informes de GA4; no se requiere ninguna configuración de evento personalizada en el lado de GA4.

• purchase – se dispara cuando se confirma el pago de una donación. Envía los campos estándar de comercio electrónico de GA4: transaction_id (el ID de la donación), value, currency, y un array items[] con la campaña como línea de artículo, categorizada como Recurring (recurrente) o One-Time (única).
• refund – se dispara cuando una donación se marca como reembolsada. Coincide con el transaction_id del evento purchase original para que GA4 los cruce automáticamente. Los ingresos netos en tus informes de GA4 se mantienen precisos.
• sign_up – se dispara cuando un donante crea una cuenta de usuario de WordPress en tu sitio. El evento incluye un identificador cifrado para que las donaciones posteriores del mismo donante se correlacionen con la misma persona en diferentes navegadores y dispositivos.
• login – se dispara cuando un donante recurrente inicia sesión. Útil para informes de retención en GA4.
• donation_button_click y donate_now_click – eventos de clic solo en el navegador para señales de la parte superior del embudo. Se disparan cuando un donante hace clic en un botón de donación, antes de que se envíe el formulario.

Las donaciones realizadas en el modo de prueba de Charitable se etiquetan con test_mode: true en los parámetros del evento, para que puedas filtrarlas de tus informes. Para hacerlo en GA4, crea una comparación o audiencia que excluya los eventos donde test_mode sea igual a true.

Visualización de tus datos en GA4

Una vez que hayas realizado una donación de prueba (o que haya entrado una real), Google Analytics tiene tres lugares para verificar que los datos están llegando.

En tiempo real

La forma más rápida de confirmar que el seguimiento funciona. Desde tu propiedad de GA4, abre Informes » Tiempo real. Aproximadamente 30 segundos después de completar una donación, verás el evento purchase en la tarjeta Recuento de eventos por nombre de evento a la derecha. Haz clic en cualquier nombre de evento para ver sus parámetros.

DebugView

Para la verificación paso a paso de un evento específico, abre Administrar » DebugView. Los eventos etiquetados con debug_mode aparecen aquí en tiempo real, con detalles completos de los parámetros. El botón Probar conexión etiqueta automáticamente sus eventos para DebugView, y también puedes habilitar el modo de depuración en todo el sitio añadiendo define('CHARITABLE_DEBUG', true); a tu wp-config.php.

Informes estándar

Para el análisis de ingresos, el informe más útil es Informes » Monetización » Compras de comercio electrónico. Este informe agrega tus eventos purchase en totales de ingresos desglosados por campaña (el item_name), categoría (recurrente vs. única) y fecha. Los reembolsos se restan automáticamente gracias a la coincidencia del ID de transacción de GA4. Los informes estándar se completan en 24 a 48 horas.

Para el análisis de fuentes de tráfico, consulta Informes » Adquisición » Adquisición de tráfico. Tus campañas etiquetadas con UTM aparecerán como filas separadas, con ingresos, tasa de conversión y métricas de participación para cada una.

Prueba de la función

La prueba de extremo a extremo más rápida consiste en realizar una donación real a través de tu sitio utilizando una pasarela de prueba como Stripe Test Mode. Una vez completada la donación, abre la donación en Charitable » Donaciones, expande el panel Google Analytics y confirma que la sección Eventos GA4 disparados muestra una marca de tiempo de purchase. Luego, comprueba GA4 » Informes » Tiempo real para confirmar que el evento aparece en menos de 30 segundos.

Si estás probando el evento de reembolso, cambia la donación a Reembolsada desde la lista de Donaciones. El metabox debería añadir una marca de tiempo de refund y GA4 Tiempo real debería mostrar el evento refund en menos de 30 segundos.

Solución de problemas

Los eventos no aparecen en GA4

Si tus donaciones de prueba no llegan a GA4, revisa estas comprobaciones en orden:

• Desde Charitable » Ajustes » Avanzado, confirma que el campo Google Analytics contiene tu ID de medición y no un ID de contenedor GTM o una propiedad UA heredada.
• Haz clic en el botón Enviar evento de prueba a GA4. El mensaje de error indicará el problema específico (secreto de API no válido, ID de medición no válido, error de red).
• Comprueba si has iniciado sesión con un rol que has añadido a Excluir seguimiento para roles. Los usuarios excluidos no generan eventos, incluso durante las pruebas. Cierra sesión e inténtalo en una ventana de incógnito.
• Desactiva cualquier bloqueador de anuncios del navegador (uBlock Origin, AdBlock Plus, Brave Shields) para tu dominio. Bloquean la carga de gtag.js en el frontend.

Site Kit de Google ya está activo

Si tienes Google Site Kit instalado y conectado a tu propiedad de GA4, Charitable pospone la carga de gtag.js a Site Kit. Esto evita que la página cargue el script de GA4 dos veces. Los eventos de donación seguirán disparándose a través de la instancia gtag de Site Kit.

Si has instalado Site Kit pero no has conectado el módulo de Analytics, el aplazamiento de Charitable es innecesario. Los desarrolladores pueden anularlo devolviendo false desde el filtro charitable_google_analytics_is_ga4_loaded.

Aviso de conflicto de GTM de Seguimiento de Conversiones de Charitable

Si tienes el complemento Charitable Conversion Tracking instalado con un ID de contenedor GTM configurado, Charitable mostrará un aviso de administrador en las páginas de configuración de Charitable explicando que gtag.js se está suprimiendo. Esto es intencional: se espera que tu contenedor GTM cargue GA4 por sí mismo, y cargar gtag.js encima duplicaría el recuento de visitas a páginas.

Si tu contenedor GTM no incluye realmente una etiqueta GA4, esta supresión es incorrecta para tu configuración. Anúlala con el filtro charitable_google_analytics_is_ga4_loaded.

Los eventos del lado del servidor no se activan

El seguimiento del lado del servidor solo se activa cuando tanto el ID de medición como el secreto de la API del Protocolo de Medición están configurados. Si tus eventos de reembolso o las donaciones fuera del sitio no aparecen en GA4, pero las donaciones en el sitio sí, es probable que falte el secreto de la API o que sea inválido. Usa el botón Probar conexión para confirmarlo.

Si el secreto de la API está configurado y la prueba se realiza correctamente, pero los cambios de estado reales no generan eventos, revisa el metabox de Google Analytics de la donación. La sección Consentimiento en la inserción puede mostrar statistics: Denegado, en cuyo caso el complemento omite correctamente los eventos del lado del servidor para las donaciones de ese donante.

¡Eso es todo! Ahora tienes GA4 rastreando tus donaciones de Charitable de extremo a extremo, con datos de atribución fluyendo tanto a Google Analytics como a tu administrador de WordPress. A continuación, consulta Conectar otras extensiones de Charitable para emparejar este complemento con el seguimiento de conversiones para píxeles de Meta y TikTok, o con el complemento de suscripciones para análisis de suscripciones.

Filtros

El complemento expone 12 filtros que cubren la detección del cargador, la personalización de la carga útil, el consentimiento, la atribución y el hash de identidad. Los nombres de los filtros siguen un prefijo charitable_google_analytics_* y pasan el valor que se está filtrando como primer argumento.

charitable_google_analytics_is_ga4_loaded

Si otro plugin ya está cargando GA4 en la página. Cuando es true, el complemento no inyectará su propio gtag.js para evitar la doble carga. Los cargadores detectados incluyen MonsterInsights, Site Kit by Google y Charitable Conversion Tracking con un ID de contenedor GTM configurado.

apply_filters( 'charitable_google_analytics_is_ga4_loaded', $is_loaded );

Úsalo cuando tengas un cargador GA4 no predeterminado (por ejemplo, una etiqueta de tema personalizada) que el complemento no detecta automáticamente. Devolver true suprime la inyección de gtag.js del propio complemento.

charitable_google_analytics_purchase_payload

La carga útil del evento purchase del lado del navegador construida en la página de recibo de donación (Fase A). Se activa antes de que se emita el bloque <script> en línea en el pie de página.

apply_filters(
    'charitable_google_analytics_purchase_payload',
    array $payload,
    Charitable_Donation $donation
);

La matriz $payload contiene campos de comercio electrónico de GA4 (transaction_id, value, currency, items). Devolver una matriz vacía ([]) omite la activación del evento para esa donación.

charitable_google_analytics_mp_purchase_payload

La carga útil purchase del Protocolo de Medición del lado del servidor (Fase B). Se activa antes de la llamada wp_remote_post() a GA4.

apply_filters(
    'charitable_google_analytics_mp_purchase_payload',
    array $payload,
    Charitable_Donation $donation
);

El $payload es el cuerpo completo de MP (client_id, user_id opcional, events[]). Devolver una carga útil con events vacíos omite la llamada.

charitable_google_analytics_mp_refund_payload

Misma forma que mp_purchase_payload, pero disparado antes del evento refund POST del lado del servidor.

apply_filters(
    'charitable_google_analytics_mp_refund_payload',
    array $payload,
    Charitable_Donation $donation
);

charitable_google_analytics_mp_signup_payload

El payload sign_up del lado del servidor construido cuando se registra un nuevo usuario de WordPress.

apply_filters(
    'charitable_google_analytics_mp_signup_payload',
    array $payload,
    WP_User $user
);

Úselo para suprimir eventos de registro para roles específicos o para inyectar parámetros de evento personalizados (por ejemplo, fuente de registro).

charitable_google_analytics_mp_login_payload

El payload login del lado del servidor construido cuando un usuario de WordPress inicia sesión.

apply_filters(
    'charitable_google_analytics_mp_login_payload',
    array $payload,
    WP_User $user
);

Un uso común es omitir los eventos de inicio de sesión para usuarios con capacidades administrativas.

charitable_google_analytics_persist_utm

¿Debería el complemento persistir los parámetros UTM de la URL de la solicitud en cookies de origen en init? Por defecto true.

apply_filters( 'charitable_google_analytics_persist_utm', $persist );

Devolver false deshabilita las escrituras de cookies UTM por completo. Útil para sitios que desean manejar la persistencia de UTM ellos mismos a través de un mecanismo personalizado.

charitable_google_analytics_utm_first_touch

¿Usar atribución UTM de primer contacto en lugar del último contacto predeterminado? Por defecto false.

apply_filters( 'charitable_google_analytics_utm_first_touch', $first_touch );

Cuando es true, se escribe una cookie UTM solo si aún no existe. El primer UTM al que se atribuyó el donante gana para la ventana de 30 días de la cookie.

charitable_google_analytics_has_consent

La decisión de consentimiento para una categoría dada en el momento de la evaluación. Recibe el resultado de la API de consentimiento de WP y le permite anular.

apply_filters(
    'charitable_google_analytics_has_consent',
    bool $consent,
    string $category,    // 'statistics' or 'marketing'
    int $donation_id     // 0 in live mode, donation ID in stored mode
);

El modo en vivo ($donation_id === 0) se usa para el control del lado del navegador como la inyección de gtag.js. El modo almacenado ($donation_id > 0) se usa para llamadas MP del lado del servidor y lee el estado de consentimiento capturado en la inserción de la donación. Devolver false suprime el seguimiento de esa categoría.

charitable_google_analytics_consent_default

El estado predeterminado del modo de consentimiento v2 emitido en el encabezado del documento antes de que se cargue gtag.js.

apply_filters(
    'charitable_google_analytics_consent_default',
    array $consent_default
);

$consent_default contiene cuatro claves: ad_user_data, ad_personalization, ad_storage y analytics_storage, cada una establecida en 'granted' o 'denied'. Devolver 'granted' para las cuatro desactiva efectivamente el modelado del modo de consentimiento v2 para esta carga de página.

charitable_google_analytics_user_id

El ID de usuario hasheado adjunto a los payloads MP como user_id. El valor predeterminado es sha256(normalized_email), donde el correo electrónico se convierte a minúsculas y se eliminan las subdirecciones.

apply_filters(
    'charitable_google_analytics_user_id',
    string $user_id,
    Charitable_Donation $donation
);

Devolver una cadena vacía suprime el campo user_id por completo. El filtro recibe el hash final, no el correo electrónico sin procesar; si necesita un esquema de identidad diferente, devuelva su propio hash estable por persona aquí.

charitable_google_analytics_client_ip

La IP del cliente utilizada como fuente para la anonimización de IP. Por defecto es REMOTE_ADDR. Los sitios detrás de una CDN o un proxy inverso que coloca la IP real del donante en una cabecera reenviada deberían anular esto.

apply_filters( 'charitable_google_analytics_client_ip', string $ip );

El valor devuelto se trunca a /24 (IPv4) o /48 (IPv6) antes de pasarlo a GA4 como el parámetro ip_override.

Acciones

El complemento dispara dos acciones por cada llamada al protocolo de medición del lado del servidor: una en caso de éxito y otra en caso de error. Ambas permiten a las integraciones de terceros reaccionar a la entrega de conversiones de GA4 en tiempo real.

charitable_google_analytics_event_sent

Se dispara tras una respuesta 2xx de mp/collect.

do_action(
    'charitable_google_analytics_event_sent',
    string $event_label,    // e.g. 'purchase', 'refund', 'sign_up', 'login'
    int $donation_id,       // 0 for non-donation events
    array $payload,         // the MP body that was sent
    int $http_code          // typically 204
);

Úsalo para duplicar eventos a un CDP como HubSpot o Segment, disparar un webhook de Zapier, actualizar un panel de análisis o cualquier otra cosa que deba reaccionar a una conversión confirmada.

charitable_google_analytics_event_failed

Se dispara ante un error de red (respuesta WP_Error) o un estado HTTP que no sea 2xx.

do_action(
    'charitable_google_analytics_event_failed',
    string $event_label,
    int $donation_id,
    array $payload,
    string $error           // WP_Error message or 'HTTP <code>'
);

Úsalo para alertar a operaciones, poner en cola una reintento a través de tu propio sistema de trabajos o recurrir a un canal alternativo.

Claves meta de donación

El complemento almacena todo lo que captura sobre una donación como metadatos estándar de las entradas de WordPress. Puedes consultarlos directamente con get_post_meta() o a través de wp post meta get de WP-CLI.

Clave de metadatos	Establecido por	Tipo	Qué contiene
_charitable_ga_client_id	capture_session() en charitable_after_save_donation	cadena	ID de cliente de GA4 analizado de la cookie _ga del donante al insertar la donación. Formato: <parte1>.<parte2>.
_charitable_ga_session_id	Igual	cadena	ID de sesión de GA4 analizado de la cookie _ga_<container> del donante.
_charitable_ga_ip_override	Igual	cadena	IP del donante anonimizada (IPv4 /24 o IPv6 /48).
_charitable_ga_consent_statistics	Igual	'granted' o no establecido	Estado de la API de Consentimiento de WP para la categoría statistics al insertar. Los metadatos vacíos se consideran permisivos.
_charitable_ga_consent_marketing	Igual	'granted' o no establecido	Igual para marketing.
_charitable_ga_utm_source	Igual	cadena	Fuente UTM de la cookie de origen del donante (o $_REQUEST como respaldo).
_charitable_ga_utm_medium	Igual	cadena	Medio UTM.
_charitable_ga_utm_campaign	Igual	cadena	Campaña UTM.
_charitable_ga_utm_term	Igual	cadena	Término UTM.
_charitable_ga_utm_content	Igual	cadena	Contenido UTM.
_charitable_ga_utm_id	Igual	cadena	ID de UTM.
_charitable_ga_purchase_fired	fire_purchase_event() (Fase A) y fire_purchase_mp() (Fase B)	Cadena de fecha y hora de MySQL	Marca de tiempo del primer evento de compra exitoso. Compartido entre la Fase A y la Fase B; el primero que se active lo establecerá.
_charitable_ga_refund_fired	fire_refund_mp()	Cadena de fecha y hora de MySQL	Marca de tiempo del evento de reembolso exitoso. Separado de la marca de compra.

Todas las claves meta tienen el prefijo de un solo guion bajo, lo que significa que están ocultas en la interfaz estándar de campos personalizados en la pantalla de edición de donaciones. Aparecen en su lugar en el metabox “Google Analytics” del complemento.

Nombres de cookies

El complemento escribe las siguientes cookies en el navegador del donante:

• charitable_ga_utm_source, charitable_ga_utm_medium, charitable_ga_utm_campaign, charitable_ga_utm_term, charitable_ga_utm_content, charitable_ga_utm_id – cookies de origen establecidas en init cada vez que un parámetro UTM está presente en la URL de la solicitud. Duración 30 días, ruta /, SameSite Lax, Secure cuando SSL está activo.

También lee estas cookies establecidas por el propio gtag.js:

• _ga – origen del client_id de GA4
• _ga_<container> – origen del session_id de GA4. La porción <container> es el ID de medición con el G- inicial eliminado.

Claves de opciones de configuración

La configuración del complemento reside en la opción de WordPress charitable_settings. Puedes leerla a través de charitable_get_option( $key, $default ):

Clave de opción	Tipo	Predeterminado	Descripción
ga4_tracking_id	cadena	''	El ID de medición de GA4 (G-XXXXXXXXXX).
ga4_mp_api_secret	cadena	''	El secreto de la API de Measurement Protocol. Requerido para el seguimiento del lado del servidor.
ga4_consent_integration	booleano	1	¿Honrar el estado de la API de Consentimiento de WP?
ga4_excluded_roles	string[]	[]	Matriz de identificadores de roles a excluir del seguimiento.

Constantes

Dos constantes de WordPress cambian el comportamiento de ejecución del complemento:

• CHARITABLE_DEBUG (verdadero/falso) – cuando es verdadero, el complemento escribe un rastro paso a paso en Herramientas » Registros con source: google-analytics, y añade debug_mode: 1 a todas las cargas útiles de eventos MP de GA4 para que aparezcan en GA4 » Admin » DebugView. Defina en wp-config.php para sitios de desarrollo.
• SCRIPT_DEBUG (verdadero/falso) – cuando es verdadero, el complemento pone en cola el archivo fuente charitable-google-analytics.js no minimizado en lugar de la compilación de producción minimizada. Útil al depurar el comportamiento del frontend.

Recetas comunes

Cambiar la atribución UTM de último toque a primer toque

add_filter( 'charitable_google_analytics_utm_first_touch', '__return_true' );

La primera UTM a la que se atribuyó el donante dentro de la ventana de cookies de 30 días permanece. Las visitas posteriores con UTM diferentes se ignoran.

Capturar la IP real del donante detrás de Cloudflare

add_filter( 'charitable_google_analytics_client_ip', function( $ip ) {
    if ( ! empty( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) {
        $candidate = sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) );
        if ( filter_var( $candidate, FILTER_VALIDATE_IP ) ) {
            return $candidate;
        }
    }
    return $ip;
} );

La IP devuelta todavía se anonimiza a /24 (IPv4) o /48 (IPv6) antes de enviarse a GA4 – el filtro solo cambia qué IP se anonimiza.

Reflejar cada donación confirmada a un CDP

add_action( 'charitable_google_analytics_event_sent',
    function( $event_label, $donation_id, $payload, $http_code ) {
        if ( 'purchase' !== $event_label ) {
            return;
        }
        // POST to your CDP, fire a Zapier webhook, etc.
        wp_remote_post( 'https://cdp.example.com/events', array(
            'body'    => wp_json_encode( $payload ),
            'headers' => array( 'Content-Type' => 'application/json' ),
            'timeout' => 5,
        ) );
    },
    10,
    4
);

Tanto los eventos exitosos como los fallidos disparan acciones, por lo que también puede reintentar los eventos fallidos a través de su propio sistema de trabajos.

Omitir eventos de inicio de sesión para administradores

add_filter( 'charitable_google_analytics_mp_login_payload',
    function( $payload, $user ) {
        if ( user_can( $user, 'manage_options' ) ) {
            return array_merge( $payload, array( 'events' => array() ) );
        }
        return $payload;
    },
    10,
    2
);

Una matriz events vacía le dice al complemento que omita la llamada MP sin alterar otros tipos de eventos.

Añadir un parámetro de evento personalizado a cada compra

add_filter( 'charitable_google_analytics_mp_purchase_payload',
    function( $payload, $donation ) {
        if ( ! empty( $payload['events'][0]['params'] ) ) {
            $payload['events'][0]['params']['organization_id'] = '12345';
        }
        return $payload;
    },
    10,
    2
);

Úselo para instalaciones de WordPress con varias organizaciones donde cada donación debe llevar una etiqueta de organización para la segmentación de GA4.

Anular el user_id del donante con su propio esquema de identidad

add_filter( 'charitable_google_analytics_user_id',
    function( $hashed_email, $donation ) {
        $crm_id = get_post_meta( $donation->ID, '_my_crm_donor_id', true );
        if ( $crm_id ) {
            return hash( 'sha256', 'crm:' . $crm_id );
        }
        return $hashed_email;
    },
    10,
    2
);

El filtro recibe el hash predeterminado del complemento; puede reemplazarlo con su propio hash estable por persona. Devolver una cadena vacía suprime el campo user_id por completo.

Orden de disparo de ganchos

Para un flujo de donación típico que se completa en el sitio, los ganchos relevantes se activan en este orden:

1. init (prioridad 10) – charitable_google_analytics_persist_utm() escribe cookies UTM si la URL de la solicitud tiene parámetros UTM.
2. wp_head (prioridad 1) – se emiten el modo de consentimiento v2 predeterminado en línea y la etiqueta de script gtag.js, controlados por charitable_google_analytics_is_ga4_loaded y la verificación de exclusión de roles.
3. wp_footer (prioridad 1) – se emiten las llamadas gtag('js') y gtag('config').
4. El donante envía el formulario de donación. Se ejecuta el flujo de la pasarela impulsado por AJAX o redirección.
5. charitable_after_save_donation (prioridad 10) – capture_session() lee las cookies del donante y almacena el client_id de GA4, session_id, IP anonimizada, valores UTM y estado de consentimiento como metadatos de donación.
6. La pasarela confirma el pago (sincrónicamente para en el sitio, mediante webhook para fuera del sitio).
7. charitable_donation_status_changed (prioridad 10) – fire_purchase_mp() envía el evento purchase del lado del servidor. La acción charitable_google_analytics_event_sent se activa al tener éxito.
8. charitable_donation_receipt_page (solo navegador) – fire_purchase_event() añade una devolución de llamada wp_footer que emite el script en línea gtag('event', 'purchase', ...). El metadato _charitable_ga_purchase_fired se establece dentro de esa devolución de llamada wp_footer (no de forma síncrona) para que la representación del recibo por correo electrónico no active el indicador de idempotencia.

Para un reembolso: el paso 7 anterior se vuelve a activar con new_status === 'charitable-refunded', y fire_refund_mp() envía el evento refund.

Para un registro o inicio de sesión: solo los pasos 1, 2 y 3 anteriores se aplican al contexto del navegador. Los pasos 5-8 se reemplazan por user_register o wp_login, que activan fire_signup_mp() o fire_login_mp() respectivamente.

¡Eso es todo! Ahora tienes la superficie completa de hooks para el complemento Charitable Google Analytics. A continuación, consulta la Guía completa de Google Analytics en Charitable para obtener documentación de configuración y administración, o el centro de Documentación para desarrolladores de Charitable para ver los hooks del resto de Charitable.

Preguntas frecuentes

P: ¿Funcionará esto con PayPal Standard u otras pasarelas externas?

R: Sí, siempre que hayas configurado la API Secret del Protocolo de Medición de GA4. La ruta del lado del servidor de Charitable captura cada donación que transiciona a Pagada, independientemente de si el navegador del donante regresó o no a tu sitio.

P: ¿Cumple con el RGPD?

R: Charitable admite el cumplimiento del RGPD y del EEE a través del Modo de consentimiento de Google v2 y el marco de la API de consentimiento de WP. Las IPs de los donantes se anonimizan antes de la transmisión, y los correos electrónicos de los donantes se codifican en un resumen SHA-256 unidireccional antes de convertirse en el ID de usuario de GA4. El correo electrónico completo nunca se envía a Google.

P: ¿Entra en conflicto con Site Kit de Google o MonsterInsights?

R: No. Charitable detecta automáticamente ambos complementos y pospone la carga de gtag.js cuando uno de ellos está activo, por lo que nunca terminas con el script de GA4 cargado dos veces en la misma página. Los eventos de donación aún se activan a través del cargador que esté a cargo.

P: ¿Cuánto tiempo tardan en aparecer los eventos en los informes de GA4?

R: Realtime y DebugView muestran los eventos en aproximadamente 30 segundos. Los informes estándar (incluidas las compras de comercio electrónico de Monetización ») se completan en 24 a 48 horas.

P: ¿Puedo excluir a mi personal del seguimiento?

R: Sí: usa el campo Excluir seguimiento para roles en Charitable » Configuración » Avanzado y selecciona los roles de WordPress que deseas excluir. Los usuarios excluidos omiten tanto la parte del navegador como las partes aplicables al rol del seguimiento del lado del servidor.

¿Se registran las donaciones realizadas en el modo de prueba de Charitable?

Sí, pero se etiquetan con test_mode: true en los parámetros del evento para que puedas filtrarlas de tus informes de GA4. Crea una comparación o audiencia de GA4 que excluya los eventos donde test_mode sea igual a true para mantener limpios tus informes de producción.

¿Son estables estos hooks entre versiones?

Todos los hooks documentados aquí se introdujeron en la versión 1.1.0 y forman parte de la API pública del complemento. Las firmas de filtros y acciones se versionan mediante la etiqueta @since en el código fuente. Los cambios disruptivos se anunciarán en el registro de cambios con un aviso de desaprobación en la versión anterior.

¿Cómo desactivo un evento específico por completo?

Utiliza el filtro de carga útil correspondiente y devuelve una matriz con events vacíos. Por ejemplo, para suprimir todos los eventos de refund del lado del servidor:

add_filter( 'charitable_google_analytics_mp_refund_payload',
    function( $payload ) {
        return array_merge( $payload, array( 'events' => array() ) );
    }
);

¿Puedo añadir dimensiones personalizadas a los eventos de GA4?

Sí. Las dimensiones personalizadas de GA4 se envían como parámetros de evento. Utiliza charitable_google_analytics_mp_purchase_payload (o el filtro correspondiente para otros eventos) para insertar tu parámetro personalizado en $payload['events'][0]['params']. Asegúrate de que el nombre del parámetro coincida con el "nombre del parámetro de evento" de tu dimensión personalizada en el administrador de GA4.

¿Cómo compruebo que mi hook personalizado se está activando?

Define define( 'CHARITABLE_DEBUG', true ); en wp-config.php, luego comprueba Herramientas » Registros filtrados por origen google-analytics. Las llamadas MP exitosas registran entradas de nivel informativo. Añade una llamada error_log() dentro de tu hook para depuración puntual, o utiliza el panel "Hooks y acciones" de Query Monitor para una vista en vivo.

¿Funciona el complemento con WP-CLI?

Sí. La persistencia de UTM se omite en los contextos wp_doing_ajax() y CLI (no hay cookies que establecer), pero los hooks del lado del servidor como charitable_donation_status_changed se activan correctamente cuando se desencadenan a través de comandos de WP-CLI. Los metadatos de donación se pueden consultar a través de wp post meta get <donation-id> _charitable_ga_purchase_fired.

¿Puedo extender el complemento con mis propios tipos de eventos personalizados?

Sí. La función auxiliar charitable_google_analytics_post_mp_event() es interna, pero las acciones que dispara (event_sent / event_failed) facilitan la adición de tus propios tipos de eventos del lado del servidor. Conecta tu función de disparo de eventos a la acción de Charitable apropiada, crea tú mismo la carga útil MP y envíala por POST al mismo punto final que utiliza el complemento. La función auxiliar de credenciales MP charitable_google_analytics_get_mp_credentials() también es pública.