Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Cuando ocurre algo importante en tu programa de Embajadores, no deberías tener que abrir el panel de control para enterarte. El panel de notificaciones con icono de campana de Charitable Pro en la barra de administración de WordPress es una pequeña bandeja de entrada para los momentos que importan.

Ahora, Embajadores 3.0 conecta cuatro eventos específicos del programa a él:

• Una cola de moderación en crecimiento
• La primera recaudación de fondos de una campaña principal
• Una recaudación de fondos que supera su objetivo
• Tu programa alcanza un nuevo hito de por vida

Los cuatro eventos están diseñados para ser raros y significativos. Deberías poder echar un vistazo a la campana y confiar en que cualquier cosa allí vale tu atención. Ningún evento se dispara más de una vez por recaudación de fondos o campaña principal.

Los Cuatro Eventos

Evento	Se dispara cuando	Título del icono de campana
Estado de la cola de moderación	El recuento pendiente supera un umbral (por defecto 5) por primera vez hoy.	“5 recaudaciones de fondos pendientes de revisión”
Primera recaudación de fondos	La primera recaudación de fondos de una campaña principal se activa.	“Primera recaudación de fondos en [Título Principal]”
Objetivo alcanzado	Una recaudación de fondos supera el 100% de su objetivo por primera vez.	“[Título de la recaudación de fondos] alcanzó su objetivo”
Nivel total recaudado	El total recaudado por embajadores en todo el sitio supera un umbral de nivel (1000 $, 5000 $, 10000 $, 25000 $, 50000 $, 100000 $, 250000 $, 500000 $, 1000000 $).	“El programa de Embajadores recaudó 10.000 $ de por vida”

Cada evento utiliza un "pestillo" por evento almacenado como meta de publicación o opción, para que no se repita. Si una recaudación de fondos cae por debajo de su objetivo (reembolso) y lo supera de nuevo, el pestillo se borra y se rearma, por lo que se te notifica de nuevo.

Evento 1: Estado de la cola de moderación

Se dispara cuando el recuento de recaudaciones de fondos pendientes supera un umbral (por defecto 5) por primera vez en un día natural determinado.

La comprobación está limitada por:

• Una nueva recaudación de fondos que pasa a pendiente (para que no se dispare en cada carga de página).
• El recuento pendiente es >= al umbral.
• El pestillo de hoy aún no se ha establecido.

El cierre es una opción diaria: _charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>. Una vez establecido, no se envían más notificaciones de cola de moderación ese día.

Anular el umbral:

add_filter( 'charitable_ambassadors_notifications_moderation_queue_threshold', function () {
    return 10;  // fire only when 10+ pending
} );

Evento 2: Primera recaudación de fondos

Se dispara la primera vez que una campaña principal obtiene su primera recaudación de fondos publicada, en el momento en que el programa “cobra vida” para esa principal.

Cierre: meta (post-meta) por campaña principal _charitable_ambassadors_notif_first_fundraiser_fired. Una vez establecido, nunca se vuelve a disparar para esa principal.

Evento 3: Objetivo alcanzado

Se dispara cuando una recaudación de fondos supera el 100% de su objetivo por primera vez. La comprobación se realiza en el momento de completar la donación.

Cierre: meta (post-meta) por recaudación de fondos _charitable_ambassadors_notif_goal_reached. El cierre se anula si una donación se reembolsa posteriormente y la recaudación de fondos cae por debajo del objetivo, por lo que si lo supera de nuevo más tarde, se te notifica de nuevo.

Evento 4: Nivel de recaudación total

Se dispara cuando el total recaudado por los embajadores en todo el sitio cruza un umbral de nivel. Niveles predeterminados:

$1,000  |  $5,000  |  $10,000  |  $25,000  |  $50,000
$100,000  |  $250,000  |  $500,000  |  $1,000,000

Cada nivel es su propio cierre (opción _charitable_ambassadors_notif_total_raised_tier_<amount>), por lo que cruzar 1000 $, luego 5000 $, luego 10000 $ se dispara por separado.

Personalizar la lista de niveles:

add_filter( 'charitable_ambassadors_notifications_total_raised_tiers', function () {
    return [ 5000, 25000, 100000, 1000000 ];  // milestones we actually care about
} );

Relleno al activar

Al activar Embajadores 3.0, el plugin suprime eventos históricos preestableciendo cada cierre relevante. De lo contrario, en la primera activación recibirías una avalancha de notificaciones de “X alcanzó el objetivo” para recaudaciones de fondos que se superaron hace años.

El relleno:

• Estampa _notif_first_fundraiser_fired en cada principal que ya tenga al menos una recaudación de fondos publicada.
• Estampa _notif_goal_reached en cada recaudación de fondos ya al 100% o más.
• Estampa el _notif_total_raised_tier_<amount> apropiado para cada nivel ya superado.

No verás notificaciones históricas, pero los nuevos eventos a partir del momento de la activación se dispararán normalmente.

Consejos que vale la pena tener en cuenta

Algunas cosas que te ayudarán a sacar el máximo provecho del panel de notificaciones sin que se convierta en ruido.

• Deja los valores predeterminados solos durante el primer mes. Están ajustados para que se sientan raros. Suprime eventos solo si encuentras que uno se dispara con demasiada frecuencia para tu gusto.
• El icono de campana es un resumen, no una transmisión en tiempo real. Las notificaciones permanecen hasta que se descartan; no caducan automáticamente.
• Usa el interruptor maestro en desarrollo. No necesitas ver las actualizaciones del icono de campana mientras iteras en una personalización.
• Los niveles de recaudación total son una señal silenciosa de “estás creciendo”. A menudo, la notificación más gratificante, es literalmente una confirmación de que el programa está funcionando.

Referencia del desarrollador

El resto de esta página es para desarrolladores que personalizan o extienden el sistema de notificaciones de Embajadores.

Interruptor Maestro

Si las notificaciones del icono de campana no son útiles para tu programa, desactívalas todas en una línea:

add_filter( 'charitable_ambassadors_notifications_enabled', '__return_false' );

Esto es global. Suprime todos los eventos que dispara Embajadores. Las notificaciones propias de Pro (donación recibida, etc.) no se ven afectadas.

Control por evento

Puedes suprimir eventos individuales sin desactivar toda la funcionalidad. Cada evento tiene un filtro _should_fire_<event>:

add_filter( 'charitable_ambassadors_notifications_should_fire_moderation_queue', '__return_false' );
add_filter( 'charitable_ambassadors_notifications_should_fire_first_fundraiser', '__return_false' );
add_filter( 'charitable_ambassadors_notifications_should_fire_goal_reached', '__return_false' );
add_filter( 'charitable_ambassadors_notifications_should_fire_total_raised', '__return_false' );

Cada uno está envuelto en una llamada apply_filters en el momento del disparo, por lo que devolver false interrumpe la notificación antes de que se publique.

Personalización del contenido de eventos

Cada evento también tiene un filtro _args_<event> que recibe la matriz de argumentos antes de que se pase a la API de notificaciones de Pro. Úsalo para cambiar el título, el enlace, el cuerpo o el icono:

add_filter( 'charitable_ambassadors_notifications_args_goal_reached', function ( $args, $fundraiser_id ) {
    $args['title'] = '🎯 ' . $args['title'];
    $args['link']  = get_edit_post_link( $fundraiser_id );  // link to edit instead of view
    return $args;
}, 10, 2 );

Almacenamiento

Cierre	Clave	Ámbito
Cola de moderación (diaria)	_charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>	opción
Primera recaudación de fondos (por padre)	_charitable_ambassadors_notif_first_fundraiser_fired	meta de publicación en el padre
Objetivo alcanzado (por recaudación de fondos)	_charitable_ambassadors_notif_goal_reached	meta de publicación en la recaudación de fondos
Nivel total recaudado (por nivel)	_charitable_ambassadors_notif_total_raised_tier_<amount>	opción

API de Pro

Las notificaciones se publican a través de la API pública de Pro:

Charitable_Local_Notifications::add( $args );

La forma y el almacenamiento de los argumentos son de Pro; Embajadores solo llama.

Atención: Charitable_Local_Notifications::add() almacena las entradas como una lista indexada numéricamente, no como un mapa indexado por ID. Si consulta el almacenamiento subyacente directamente, trátelo como una lista.

Filtros

Filtro	Predeterminado	Propósito
charitable_ambassadors_notifications_enabled	verdadero	Interruptor maestro.
charitable_ambassadors_notifications_should_fire_<event>	verdadero	Supresión por evento.
charitable_ambassadors_notifications_args_<event>	calculado	Modificador de argumentos por evento.
charitable_ambassadors_notifications_moderation_queue_threshold	5	Umbral del recuento pendiente.
charitable_ambassadors_notifications_total_raised_tiers	matriz de 9	Cantidades de nivel en orden ascendente.

Acciones

Acción	Args	Se dispara cuando
charitable_ambassadors_notification_fired	$event_slug, $args	Se publicó una notificación en el icono de campana de Pro.
charitable_ambassadors_notification_suppressed	$event_slug, $reason	Se suprimió una notificación (interruptor, por evento o bloqueo activado).

Clase de desencadenadores

Charitable_Ambassadors_Notification_Triggers::get_instance();

Singleton. Todos los oyentes de eventos se registran en su __construct(). Puede usar remove_action() para deshabilitar oyentes específicos por referencia si necesita una deshabilitación quirúrgica.

Exclusión en modo de prueba

La comprobación del nivel de recaudación total excluye las donaciones marcadas con _postmeta('test_mode') = '1'. La exclusión se encuentra en Charitable_Ambassadors_Overview_Data::get_donation_aggregates(), que es reutilizada por el notificador.

Capacidades

El panel del icono de campana está restringido por la capacidad estándar de Pro. Las notificaciones de embajadores heredan esa restricción.

Ejemplos de personalización

Ajustes comunes. Añada cualquiera de estos a functions.php de su tema o a un plugin específico del sitio.

Reemplace el texto "5 recaudaciones pendientes de revisión" con el lenguaje de su equipo:

add_filter( 'charitable_ambassadors_notifications_args_moderation_queue', function ( $args, $count ) {
    $args['title'] = sprintf( '%d fundraisers need your review (huddle time)', $count );
    return $args;
}, 10, 2 );

Reflejar todas las notificaciones de Embajadores en Slack:

add_action( 'charitable_ambassadors_notification_fired', function ( $event_slug, $args ) {
    wp_remote_post( 'https://hooks.slack.com/...', [
        'body'    => json_encode( [
            'text' => "*{$event_slug}*: " . ( $args['title'] ?? '' ),
        ] ),
        'headers' => [ 'Content-Type' => 'application/json' ],
    ] );
}, 10, 2 );

Restablecer el bloqueo del "primer recaudador" para pruebas (volver a ejecutar la notificación):

delete_post_meta( $parent_id, '_charitable_ambassadors_notif_first_fundraiser_fired' );
// Now the next published fundraiser on this parent will re-fire the event.

Diferentes niveles para dos sitios diferentes en una instalación multisitio:

add_filter( 'charitable_ambassadors_notifications_total_raised_tiers', function ( $tiers ) {
    if ( is_main_site() ) {
        return [ 25000, 100000, 500000, 1000000 ];
    }
    return [ 1000, 5000, 10000 ];
} );

Conclusión

Eso cubre los eventos de notificación de Embajadores, desde cómo se activan hasta cómo ajustarlos. Funcionan automáticamente desde la activación y no requieren configuración para ser útiles. Si desea ajustar el umbral de moderación, cambiar los niveles de hitos o redirigir las notificaciones a Slack, los filtros y ejemplos de personalización anteriores cubren todos esos casos.

Si tiene preguntas sobre alguno de los eventos de notificación o la API de notificaciones de Pro, nuestro equipo de soporte estará encantado de ayudarle.

También te Puede Interesar Leer

Estos documentos cubren las características más estrechamente conectadas con los eventos que activan las notificaciones de Embajadores.

• Panel de control general: el evento de nivel de recaudación total utiliza la clase de datos generales, y el panel es donde verá sus números a nivel de programa.
• Moderación: a dónde le lleva la notificación de estado de la cola de moderación cuando el recuento pendiente supera el umbral.
• Plantillas de correo electrónico: la superficie transaccional de correo electrónico de las notificaciones dirigidas a los embajadores.
• Ganchos y filtros en Embajadores: la referencia completa de filtros y acciones para todo el complemento Embajadores.