Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

La sección General es la pantalla de inicio de su programa de recaudación de fondos entre pares. Es la primera página que verá al abrir Embajadores en su administrador de WordPress, y está diseñada para que pueda responder las preguntas que todo gerente de programa se hace cada mañana:

• ¿Cuánto hemos recaudado este mes?
• ¿Quién es nuestro principal recaudador en este momento?
• ¿Se están registrando nuevos embajadores o el crecimiento se ha estancado?
• ¿Qué campañas están dando sus frutos?

En lugar de que usted ejecute informes o arme listas de donaciones, la sección General lo muestra todo de un vistazo.

Cuándo usarlo

Algunos momentos comunes en los que la sección General demuestra su valía:

• Revisión de lunes por la mañana: seleccione “Últimos 7 días” y escanee los indicadores clave de rendimiento para ver cómo fue el fin de semana.
• Informe mensual para la junta: cambie a “Último mes”, haga clic en Imprimir resumen y tendrá una instantánea de una página para su reunión.
• Análisis retrospectivo al final de la campaña: seleccione un rango personalizado que cubra el período de la campaña y descargue los CSV de cada sección.
• Identificar una causa con dificultades: el gráfico circular de Principales campañas principales resalta la concentración de causas; la lista de Principales embajadores muestra a quién podría agradecer públicamente para mantener el impulso.

Encontrar la sección General

Una vez que Charitable Ambassadors esté instalado y activado, encontrará la sección General en:

Administrador de WordPress » Charitable » Embajadores » General

Es la pestaña más a la izquierda y la página de destino predeterminada para el área de Embajadores, por lo que la mayoría de las veces no necesitará hacer clic en nada para llegar allí.

Las tres cosas que hará con más frecuencia

1. Seleccionar un intervalo de fechas

Todo en la sección General respeta el intervalo de fechas seleccionado en la parte superior derecha de la página. Haga clic en la entrada de fecha y elija entre los preajustes:

• Últimos 7 días, Últimos 14 días, Últimos 30 días (el predeterminado), Últimos 90 días
• Este mes, Último mes, Este año
• De por vida: todas las donaciones desde que comenzó
• Personalizado: abre un calendario para que pueda elegir cualquier par de fechas

El intervalo que elija se recordará solo para usted; la próxima vez que visite, la página se cargará automáticamente en el mismo intervalo. Si comparte un inicio de sesión con un compañero de equipo, verá su propio valor predeterminado.

2. Leer los números principales

Los seis recuadros grandes en la parte superior son el titular de su programa:

Mosaico	Lo que significa en lenguaje claro
Recaudado	Dólares totales que ingresaron a través de campañas de embajadores durante el intervalo que eligió.
Donaciones	Cuántos regalos se recibieron, contando cada donación como una (incluso varios regalos de la misma persona).
Donantes	Cuántas personas únicas donaron. Alguien que donó dos veces cuenta como una.
Recaudadores Activos	Cuántos recaudadores individuales recibieron al menos una donación en el período. La línea inferior ("17 de 31 embajadores verificados") es de por vida, para que puedas ver cuántos de tu lista están validados.
Nuevos Embajadores	Cuántas personas crearon su primer evento de recaudación durante el período: tu indicador de crecimiento.
Donación Media	El importe medio en euros por donación. Útil para detectar cambios en el comportamiento de los donantes.

La pequeña flecha junto a cada número lo compara con el período anterior de igual duración. Flecha verde hacia arriba = crecimiento; flecha roja hacia abajo = declive. Si el valor actual o el anterior es cero, la flecha se suprime para que nunca veas un "-100% desde 0 €" sin sentido.

3. Identifica a tus Mejores Colaboradores

Debajo de los recuadros principales encontrarás las clasificaciones de recaudadores, embajadores y campañas principales:

• Mejores Recaudadores: los 5 recaudadores individuales que consiguieron más dinero en el período.
• Mejores Embajadores: las 5 personas (creadores de campañas) que recaudaron personalmente más, incluso si organizaron varios eventos de recaudación.

• Mejores Campañas Principales: un gráfico circular que muestra qué causas atraen más. Útil para detectar la concentración de causas ("oh, el 70% de nuestro dinero va a la maratón, deberíamos conseguir más apoyo para las otras causas también").

Haz clic en cualquier nombre del widget de Mejores Embajadores para abrir su perfil completo en el Directorio.

Observando la Tendencia a lo Largo del Tiempo

El gráfico Donaciones a lo Largo del Tiempo en el centro de la página muestra tu velocidad de recaudación:

Dos capas se apilan una encima de la otra:

• Verde son las donaciones realizadas directamente a tus campañas principales (de causa).
• Naranja son las donaciones realizadas a los recaudadores individuales debajo.

Cuanto mayor sea el área naranja en relación con la verde, más están impulsando los recaudadores el programa en lugar de las donaciones directas. Esa suele ser la señal de un esfuerzo de "peer-to-peer" saludable.

Los bloques en la parte inferior cambian automáticamente según el período que hayas elegido:

• Elige un período de hasta 90 días y verás barras día a día.
• Elige un trimestre o un año y el gráfico cambiará a semanas.
• Elige "De por vida" o un período de varios años y obtendrás bloques mensuales.

Haz clic en Descargar CSV en la parte superior derecha del gráfico para exportar los datos agrupados, útil si quieres incluirlo en una hoja de cálculo para tu presentación a la junta directiva.

Seguimiento de la Actividad de Reclutamiento

Si has activado las Invitaciones, la función que permite a tus embajadores actuales reclutar a otros nuevos, verás un widget de Reclutamiento más abajo en la página.

Muestra cuántos nuevos embajadores llegaron a través de enlaces de invitación personal, desglosados por estado (Aprobado, Pendiente, Rechazado), con un gráfico de velocidad de reclutamiento y una tabla de los mejores reclutadores. Si aún no has activado las Invitaciones, solo verás una tarjeta de estado vacío con un enlace para activarlas.

La Actividad Más Reciente

Desplázate hasta abajo y encontrarás Donaciones recientes: los ocho regalos más recientes de todas las campañas de embajadores en tu sitio, con avatares de donantes y marcas de tiempo de “hace 5 minutos”. A diferencia de todo lo demás en la página, esta lista ignora el rango de fechas que elegiste en la parte superior; siempre muestra la actividad más reciente para que puedas ver lo que está sucediendo ahora mismo.

Exportar los datos

La mayoría de las secciones en la Descripción general tienen un botón Descargar CSV en su encabezado:

• Sección de KPI: CSV de los seis números principales + tendencias
• Donaciones a lo largo del tiempo: totales por categoría
• Principales recaudadores de fondos, Principales embajadores, Principales padres: listas clasificadas
• Reclutamiento: el registro completo de reclutas para el rango

Estos son archivos CSV puros (cada celda se ha saneado para evitar la inyección de fórmulas de Excel), limitados a 10.000 filas para que puedas abrirlos de forma segura en cualquier programa de hojas de cálculo.

Imprimir un documento de una página

Haz clic en el icono de la impresora junto al selector de rango de fechas, y tu navegador abrirá una vista previa de impresión que eliminará la barra lateral de administración, tu otra barra de administración y el encabezado de la página, dejando solo un documento limpio de una página que puedes guardar como PDF para reuniones de junta o compartir con tu director.

Qué hacer si ves todo a ceros

Una Descripción general en blanco suele significar una de estas tres cosas:

Lo que ves	Lo que está pasando	Cómo solucionarlo
Una tarjeta “Empezar” con una lista de tus campañas	Aún no has habilitado el sistema de recaudación entre pares (peer-to-peer) en ninguna campaña.	Haz clic en Habilitar recaudación entre pares en una campaña; estás eligiendo la causa para la que tus embajadores recaudarán fondos.
Un banner que dice “aún no hay recaudadores de fondos”	Tienes una campaña habilitada para recaudación entre pares, pero ningún embajador se ha registrado aún para recaudar fondos para ella.	Comparte la URL de envío de esa campaña con posibles embajadores, o configura Invitaciones.
Gráficos esqueléticos con “Aún no hay donaciones”	Tienes recaudadores de fondos, pero no se recibieron donaciones durante el rango de fechas que has seleccionado.	Intenta cambiar a “Toda la vida”; es posible que tus datos sean simplemente anteriores al rango.

Consejos

• Las fichas, gráficos y listas de KPI se almacenan en caché durante 5 minutos para mantener la página ágil. Si acabas de hacer un cambio y quieres verlo de inmediato, haz clic en el icono circular de actualización junto al selector de fecha.
• Pasa el ratón sobre las pequeñas flechas de tendencia junto a cada KPI para ver los números exactos del período anterior.
• La ficha “Pendientes de aprobación” solo aparece cuando estás usando Aprobación manual y hay al menos un recaudador de fondos esperando tu revisión. Haz clic en ella para saltar directamente a la cola de moderación.

Referencia del desarrollador

El resto de esta página es para desarrolladores que personalizan la Descripción general o la amplían.

Filtros

Filtro	Predeterminado	Propósito
embajadores_caritativos_recaudadores_de_fondos_principales_resumen_límite	5	Número de recaudadores de fondos en la tabla de Principales recaudadores de fondos (1-50).
limite_embajadores_principales_resumen_embajadores_caritativos	5	Número de embajadores en el widget Embajadores Principales.
minimo_padres_resumen_embajadores_caritativos	2	Recuento mínimo de padres-campañas antes de que se renderice el gráfico circular. Por debajo de este umbral, el gráfico circular muestra un esqueleto.
incluir_embajadores_inactivos_resumen_embajadores_caritativos	verdadero	Incluir embajadores con cero recaudación en Embajadores Principales. Establecer false para hacer un inner join en lugar de un left join de la tabla de donaciones.
ttl_transitorio_resumen_embajadores_caritativos	5 * MINUTO_EN_SEGUNDOS	TTL para la caché transitoria por sección.
preajustes_rango_resumen_embajadores_caritativos	matriz de 9 preajustes	Anular la lista de preajustes de rango de fechas que se muestra en el selector.
charitable_ambassadors_overview_csv_max_rows	10000	Límite máximo de filas en cada exportación CSV.
habilitado_bienvenida_resumen_embajadores_caritativos	verdadero	Devolver false para suprimir el aviso de bienvenida en todo el sitio.
url_documentacion_bienvenida_resumen_embajadores_caritativos	URL de documentación/actualización-complemento-embajadores-caritativos	Anular la URL a la que enlaza el aviso de bienvenida.

Acciones

Acción	Argumentos	Se dispara cuando
antes_de_los_indicadores_clave_resumen_embajadores_caritativos	–	Justo antes de que se rendericen los seis indicadores clave. Úselo para insertar un indicador o banner personalizado.
despues_de_las_donaciones_recientes_resumen_embajadores_caritativos	–	Después del widget Donaciones Recientes. Úselo para un bloque adicional al final de la página.

Endpoints AJAX

Los cuatro son solo wp_ajax_ (sin nopriv_), nonce action charitable_ambassadors_overview, capability manage_charitable_settings.

Acción	Propósito
grafico_principal_resumen_embajadores_caritativos	Devuelve la serie de Donaciones a lo largo del tiempo para el rango activo. Se llama una vez por carga de página, después de la primera pintura.
guardar_rango_resumen_embajadores_caritativos	Conserva el rango de fechas elegido por el usuario en user_meta para que se cargue en la próxima visita.
habilitar_p2p_resumen_embajadores_caritativos	Alterna el meta _campaign_supports_child_campaigns de una sola campaña desde el selector en línea de estado vacío de padres cero. Controlado por current_user_can( 'edit_post', $campaign_id ) por fila.
descartar_bienvenida_resumen_embajadores_caritativos	Indicador de ocultación por usuario para el aviso de bienvenida. Almacenado en user_meta('charitable_ambassadors_overview_welcome_dismissed').

Clase de datos

Charitable_Ambassadors_Overview_Data (singleton, get_instance()) es la fuente de datos para cada sección de Resumen. Los métodos públicos son:

get_donation_aggregates( $start, $end )       // raised, donations, donors, active_campaigns
get_new_ambassadors_count( $start, $end )     // int
get_verified_ambassador_split()               // [ 'verified' => int, 'total' => int ]
get_top_fundraisers( $start, $end, $limit )   // array of fundraiser rows
get_top_ambassadors( $start, $end, $limit )   // array of ambassador rows
get_top_parents( $start, $end )               // donut data
get_donations_by_day( $start, $end )          // hero chart data
get_recent_donations( $limit )                // range-independent, default 8
get_pending_approvals_count()                 // range-independent
calculate_trend( $current, $previous )        // { direction, percent }|null
get_total_raised_all_time()                   // float - reused by the Notifications feature
get_p2p_campaign_ids()                        // [ 'all' => [], 'parent_ids' => [], 'fundraiser_ids' => [] ]
get_recruitment_breakdown( $range )           // Invitations feature
get_recruitment_timeseries( $range )          // Invitations feature
get_top_recruiters_widget( $range, $limit )   // Invitations feature

Los argumentos de fecha son cadenas de fecha y hora de MySQL ('Y-m-d H:i:s'). Todos los métodos almacenan en caché los resultados en transitorios con clave por sección + rango de fechas.

Invalidación de caché

La caché transitoria se invalida automáticamente cuando:

• Se guarda, reembolsa o descarta una donación (charitable_donation_saved, charitable_donation_refunded).
• Un recaudador de fondos hijo transiciona dentro o fuera de publish (transition_post_status).
• Se añade, actualiza o elimina el meta _campaign_supports_child_campaigns de una campaña.

La invalidación llama a Charitable_Ambassadors_Overview_Data::bust_cache(), que:

1. ELIMINA cada fila _transient_charitable_ambassadors_overview_% de wp_options.
2. Evacúa la superclave alloptions y las entradas coincidentes por fila de la caché de objetos de WP.

La eliminación SQL bruta es intencional: $wpdb->prepare() con comodines % al final se rompió por la protección de marcadores de posición de WP 6.2, por lo que usamos una cláusula LIKE literal dentro de un $wpdb->query().

Para invalidar manualmente la caché para depuración, visita ?charitable_ambassadors_clear_overview_cache=1 mientras inicias sesión como administrador.

Exclusión en modo de prueba

Cada agregado de donaciones excluye las donaciones marcadas con _postmeta('test_mode') = '1'. La exclusión vive en get_donation_aggregates() y se transmite al gráfico principal y a las exportaciones CSV. Cambia Charitable al modo de prueba a través de Charitable » Configuración » Avanzado » Modo de prueba.

Exportaciones CSV

Formulario POST a admin-post.php?action=charitable_ambassadors_overview_csv, acción nonce charitable_ambassadors_overview_csv, capacidad manage_charitable_settings. El argumento de consulta section selecciona qué conjunto de datos:

• resumen_kpi
• donaciones_a_lo_largo_del_tiempo
• principales_recaudadores
• principales_embajadores
• principales_padres
• registro_reclutamiento
• principales_reclutadores_reclutamiento

Los nombres de archivo siguen el patrón ambassadors-<section>-<start>-to-<end>.csv. Cada celda se ejecuta a través de Charitable_Ambassadors_Overview_CSV::neutralize_csv_cell() que antepone una comilla simple ' a cualquier cadena que comience con =, +, -, @, tabulador o CR (defensa recomendada por OWASP contra la inyección de fórmulas de Excel).

Capacidades

La única puerta de capacidad es manage_charitable_settings. Esta se otorga a los Administradores por defecto. Para otorgar acceso a Resumen a un rol no administrador sin otorgar acceso a otras configuraciones de Charitable, añade la capacidad a ese rol.

Aviso de bienvenida

Una tarjeta con borde azul en la parte superior de la Descripción general enlaza a las notas de actualización de complementos 3.0. Se puede descartar por usuario, se guarda mediante el punto final AJAX charitable_ambassadors_overview_dismiss_welcome en user_meta('charitable_ambassadors_overview_welcome_dismissed').

Para suprimir el aviso en todo el sitio independientemente del estado de descarte:

add_filter( 'charitable_ambassadors_overview_welcome_enabled', '__return_false' );

Ejemplos de personalización

Algunos pequeños cambios que surgen a menudo. Inserta cualquiera de estos en el archivo functions.php de tu tema o en un plugin de fragmentos de código.

Mostrar 10 recaudaciones en la lista de Principales Recaudaciones en lugar de 5:

add_filter( 'charitable_ambassadors_overview_top_fundraisers_limit', function () {
    return 10;
} );

Ocultar embajadores que no han recaudado nada del widget de Principales Embajadores:

add_filter( 'charitable_ambassadors_overview_include_inactive_ambassadors', '__return_false' );

Caché durante 30 minutos en lugar de 5:

add_filter( 'charitable_ambassadors_overview_transient_ttl', function () {
    return 30 * MINUTE_IN_SECONDS;
} );

Reemplaza el aviso de bienvenida con un enlace a tu propia página de incorporación:

add_filter( 'charitable_ambassadors_overview_welcome_docs_url', function () {
    return home_url( '/staff-resources/p2p-getting-started/' );
} );

Añade un banner personalizado encima de los indicadores clave de rendimiento (KPI):

add_action( 'charitable_ambassadors_overview_before_kpi_tiles', function () {
    echo '
Q4 push is on - share progress in #fundraising-team!
';
} );

Relacionado

• Asistente de Configuración: el flujo de incorporación de tres vías que estructura tu primer programa peer-to-peer.
• Moderación: aprueba, rechaza y solicita cambios en las presentaciones de recaudación.
• Directorio: tu lista completa de embajadores con perfiles, donaciones y linaje de reclutamiento.
• Invitaciones: el sistema de reclutamiento que potencia el widget de Reclutamiento de arriba.
• Hooks y filtros en Embajadores – la referencia completa de filtros y acciones.