Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Lorsque quelque chose d'important se produit dans votre programme d'Ambassadeurs, vous ne devriez pas avoir à ouvrir le tableau de bord pour le savoir. Le panneau de notification avec icône de cloche de Charitable Pro dans la barre d'administration WordPress est une petite boîte de réception pour les moments importants.

Maintenant, Ambassadeurs 3.0 y connecte quatre événements spécifiques au programme :

• Une file d'attente de modération croissante
• La première collecte de fonds d'une campagne parente
• Une collecte de fonds franchissant son objectif
• Votre programme atteignant un nouveau jalon à vie

Les quatre événements sont conçus pour être rares et significatifs. Vous devriez pouvoir jeter un coup d'œil à la cloche et avoir confiance que tout ce qui s'y trouve mérite votre attention. Aucun événement ne se déclenche plus d'une fois par collecte de fonds ou par campagne parente.

Les quatre événements

Événement	Se déclenche lorsque	Titre de l'icône de cloche
Santé de la file d'attente de modération	Le nombre d'éléments en attente franchit un seuil (par défaut 5) pour la première fois aujourd'hui.	« 5 collectes de fonds en attente d'examen »
Première collecte de fonds	La première collecte de fonds d'une campagne parente est lancée.	« Première collecte de fonds sur [Titre parent] »
Objectif atteint	Une collecte de fonds dépasse 100 % de son objectif pour la première fois.	« [Titre de la collecte de fonds] a atteint son objectif »
Niveau total collecté	Le total des fonds collectés par les ambassadeurs sur l'ensemble du site franchit un seuil ($1K, $5K, $10K, $25K, $50K, $100K, $250K, $500K, $1M).	« Le programme d'ambassadeurs a collecté 10 000 $ à vie »

Chaque événement utilise un « loquet » par événement stocké sous forme de métadonnées de publication ou d'option, afin que le redéclenchement ne se produise pas. Si une collecte de fonds tombe en dessous de son objectif (remboursement) et le dépasse à nouveau, le loquet est effacé et réarmé, vous recevez donc à nouveau une notification.

Événement 1 : Santé de la file d'attente de modération

Se déclenche lorsque le nombre de collectes de fonds en attente franchit un seuil (par défaut 5) pour la première fois un jour calendaire donné.

La vérification est conditionnée par :

• Une nouvelle collecte de fonds passant à l'état en attente (afin qu'elle ne se déclenche pas à chaque chargement de page).
• Le nombre d'éléments en attente étant >= au seuil.
• Le loquet pour aujourd'hui n'étant pas encore défini.

Le loquet est une option quotidienne : _charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>. Une fois défini, aucune autre notification de file d'attente de modération ne se déclenche ce jour-là.

Remplacer le seuil :

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

Événement 2 : Premier appel aux dons

Se déclenche la première fois qu'une campagne parente reçoit son premier appel aux dons publié, au moment où le programme « prend vie » pour ce parent.

Verrou : méta-post par parent _charitable_ambassadors_notif_first_fundraiser_fired. Une fois défini, ne se déclenche plus jamais pour ce parent.

Événement 3 : Objectif atteint

Se déclenche lorsqu'un appel aux dons dépasse 100 % de son objectif pour la première fois. La vérification s'effectue au moment de la validation du don.

Verrou : méta-post par appel aux dons _charitable_ambassadors_notif_goal_reached. Le verrou est effacé si un don est ultérieurement remboursé et que l'appel aux dons passe sous l'objectif. Ainsi, s'il le dépasse à nouveau plus tard, vous recevez une nouvelle notification.

Événement 4 : Palier du total collecté

Se déclenche lorsque le total des collectes des ambassadeurs à l'échelle du site franchit un seuil de palier. Seuils par défaut :

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

Chaque palier a son propre verrou (option _charitable_ambassadors_notif_total_raised_tier_<amount>), donc franchir 1 000 $, puis plus tard 5 000 $, puis plus tard 10 000 $ déclenche des notifications distinctes.

Personnaliser la liste des paliers :

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

Remplissage rétroactif à l'activation

Lors de l'activation d'Ambassadors 3.0, le plugin supprime les événements historiques en pré-définissant chaque verrou pertinent. Sinon, lors de la première activation, vous recevriez un déluge de notifications « X a atteint son objectif » pour des appels aux dons qui ont été dépassés il y a des années.

Le remplissage rétroactif :

• Appose _notif_first_fundraiser_fired sur chaque parent qui a déjà au moins un appel aux dons publié.
• Appose _notif_goal_reached sur chaque appel aux dons déjà à 100 % ou plus.
• Appose _notif_total_raised_tier_<amount> approprié pour chaque palier déjà franchi.

Vous ne verrez aucune notification historique, mais les nouveaux événements à partir du moment de l'activation se déclencheront normalement.

Conseils à garder à l'esprit

Quelques éléments qui vous aideront à tirer le meilleur parti du panneau de notification sans qu'il ne devienne du bruit.

• Laissez les paramètres par défaut tranquilles pendant le premier mois. Ils sont réglés pour être rares. Supprimez les événements uniquement si vous constatez qu'un événement se déclenche trop souvent à votre goût.
• L'icône de cloche est un résumé, pas un flux en temps réel. Les notifications restent jusqu'à ce qu'elles soient ignorées ; elles n'expirent pas automatiquement.
• Utilisez le bouton d'arrêt principal en développement. Pas besoin de voir les mises à jour de l'icône de cloche lors de l'itération sur une personnalisation.
• Les paliers du total collecté sont un signal discret de « vous progressez ». Souvent la notification la plus gratifiante, c'est littéralement une confirmation que le programme fonctionne.

Référence développeur

Le reste de cette page est destiné aux développeurs qui personnalisent ou étendent le système de notification d'Ambassadors.

Arrêt principal

Si les notifications de l'icône de cloche ne sont pas utiles pour votre programme, désactivez-les toutes en une seule ligne :

add_filter( 'charitable_ambassadors_notifications_enabled', '__return_false' );

Ceci est global. Il supprime tous les événements déclenchés par Ambassadors. Les notifications propres à Pro (don reçu, etc.) ne sont pas affectées.

Contrôle par événement

Vous pouvez supprimer des événements individuels sans désactiver l'ensemble de la fonctionnalité. Chaque événement a un filtre _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' );

Chacun est encapsulé dans un appel apply_filters au moment du déclenchement, donc retourner false interrompt la notification avant qu'elle ne soit publiée.

Personnalisation du contenu des événements

Chaque événement dispose également d'un filtre _args_<event> qui reçoit le tableau des arguments avant qu'il ne soit transmis à l'API de notification de Pro. Utilisez-le pour modifier le titre, le lien, le corps ou l'icône :

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 );

Stockage

Verrou	Clé	Portée
File d'attente de modération (quotidienne)	_charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>	option
Premier appel aux dons (par parent)	_charitable_ambassadors_notif_first_fundraiser_fired	métadonnées de publication sur le parent
Objectif atteint (par appel aux dons)	_charitable_ambassadors_notif_goal_reached	métadonnées de publication sur l'appel aux dons
Niveau total collecté (par niveau)	_charitable_ambassadors_notif_total_raised_tier_<amount>	option

API Pro

Les notifications sont publiées via l'API publique de Pro :

Charitable_Local_Notifications::add( $args );

La structure et le stockage des arguments relèvent de Pro ; Ambassadors s'y connecte simplement.

Attention : Charitable_Local_Notifications::add() stocke les entrées sous forme de liste indexée numériquement, et non de carte indexée par ID. Si vous interrogez directement le stockage sous-jacent, traitez-le comme une liste.

Filtres

Filtre	Défaut	Objectif
charitable_ambassadors_notifications_enabled	vrai	Interrupteur général.
charitable_ambassadors_notifications_should_fire_<event>	vrai	Suppression par événement.
charitable_ambassadors_notifications_args_<event>	calculé	Modificateur d'arguments par événement.
charitable_ambassadors_notifications_moderation_queue_threshold	5	Seuil du nombre d'éléments en attente.
charitable_ambassadors_notifications_total_raised_tiers	tableau de 9	Montants des paliers par ordre croissant.

Actions

Action	Args	Se déclenche lorsque
charitable_ambassadors_notification_fired	$event_slug, $args	Une notification a été publiée dans la cloche de Pro.
charitable_ambassadors_notification_suppressed	$event_slug, $reason	Une notification a été supprimée (interrupteur, par événement ou verrouillage activé).

Classe des déclencheurs

Charitable_Ambassadors_Notification_Triggers::get_instance();

Singleton. Tous les écouteurs d'événements sont enregistrés dans son __construct(). Vous pouvez remove_action() des écouteurs spécifiques par référence si vous avez besoin d'une désactivation chirurgicale.

Exclusion du mode test

La vérification du palier total collecté exclut les dons marqués _postmeta('test_mode') = '1'. L'exclusion se trouve dans Charitable_Ambassadors_Overview_Data::get_donation_aggregates(), que le notificateur réutilise.

Capacités

Le panneau de la cloche lui-même est contrôlé par la capacité standard de Pro. Les notifications des ambassadeurs héritent de ce contrôle.

Exemples de personnalisation

Ajustements courants. Ajoutez l'un de ces éléments à votre fichier functions.php de thème ou à un plugin spécifique au site.

Remplacez le texte « 5 collectes de fonds en attente d'examen » par la terminologie de votre équipe :

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 );

Miroir de chaque notification des ambassadeurs vers 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 );

Réinitialisez le verrouillage du « premier appel à l'action » pour les tests (relancez la notification) :

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

Différents paliers pour deux sites différents dans un multisite :

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

En résumé

Cela couvre les événements de notification des ambassadeurs, de leur déclenchement à leur réglage. Ils fonctionnent automatiquement dès l'activation et ne nécessitent aucune configuration pour être utiles. Si vous souhaitez ajuster le seuil de modération, modifier les paliers de réussite ou router les notifications vers Slack, les filtres et les exemples de personnalisation ci-dessus couvrent tous ces cas.

Si vous avez des questions sur l'un des événements de notification ou sur l'API de notification Pro, notre équipe de support est heureuse de vous aider.

Vous pourriez aussi vouloir lire

Ces documents couvrent les fonctionnalités les plus étroitement liées aux événements qui déclenchent les notifications des ambassadeurs.

• Tableau de bord de présentation – l'événement de palier de montant total collecté utilise la classe de données de présentation, et le tableau de bord est l'endroit où vous verrez vos chiffres au niveau du programme.
• Modération – où la notification d'état de la file d'attente de modération vous emmène lorsque le nombre d'éléments en attente dépasse le seuil.
• Modèles d'e-mail – la surface de messagerie transactionnelle sœur pour les notifications destinées aux ambassadeurs.
• Crochets et filtres dans Ambassadors – la référence complète des filtres et des actions pour l'ensemble du module complémentaire Ambassadors.