Erfordert: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Wenn in Ihrem Botschafterprogramm etwas Bedeutendes passiert, müssen Sie nicht das Dashboard öffnen, um es herauszufinden. Das Glockensymbol-Benachrichtigungsfeld von Charitable Pro in der WordPress-Adminleiste ist eine kleine Inbox für Momente, die zählen.

Jetzt verbindet Ambassadors 3.0 vier programmspezifische Ereignisse damit:

• Eine wachsende Moderationswarteschlange
• Die erste Spendenaktion einer übergeordneten Kampagne
• Eine Spendenaktion erreicht ihr Ziel
• Ihr Programm erreicht einen neuen Meilenstein im Lebensverlauf

Die vier Ereignisse sind so konzipiert, dass sie selten und bedeutsam sind. Sie sollten einen Blick auf die Glocke werfen und darauf vertrauen können, dass alles, was dort ist, Ihre Aufmerksamkeit verdient. Kein Ereignis wird mehr als einmal pro Spendenaktion oder übergeordneter Kampagne ausgelöst.

Die vier Ereignisse

Ereignis	Wird ausgelöst, wenn	Titel des Glockensymbols
Gesundheit der Moderationswarteschlange	Die Anzahl der ausstehenden Elemente überschreitet zum ersten Mal heute einen Schwellenwert (Standard 5).	„5 Spendenaktionen warten auf Überprüfung“
Erste Spendenaktion	Die erste Spendenaktion einer übergeordneten Kampagne wird live geschaltet.	„Erste Spendenaktion auf [Parent Title]“
Ziel erreicht	Eine Spendenaktion überschreitet zum ersten Mal 100 % ihres Ziels.	„[Fundraiser Title] hat sein Ziel erreicht“
Gesamtbetrag-Stufe	Der gesamte von Botschaftern gesammelte Betrag der Website überschreitet einen Schwellenwert ($1.000, $5.000, $10.000, $25.000, $50.000, $100.000, $250.000, $500.000, $1 Mio.).	„Botschafterprogramm hat im Lebensverlauf 10.000 $ gesammelt“

Jedes Ereignis verwendet eine Ereignis-spezifische „Sperre“, die als Post-Meta oder Option gespeichert wird, sodass keine erneute Auslösung erfolgt. Wenn eine Spendenaktion unter ihr Ziel fällt (Rückerstattung) und es erneut überschreitet, wird die Sperre gelöscht und neu aktiviert, sodass Sie erneut benachrichtigt werden.

Ereignis 1: Moderationswarteschlangen-Gesundheit

Wird ausgelöst, wenn die Anzahl der ausstehenden Spendenaktionen zum ersten Mal an einem bestimmten Kalendertag einen Schwellenwert (Standard 5) überschreitet.

Die Prüfung wird gesteuert durch:

• Eine neue Spendenaktion, die in den Status „ausstehend“ übergeht (damit sie nicht bei jedem Seitenaufruf ausgelöst wird).
• Die Anzahl der ausstehenden Elemente ist >= Schwellenwert.
• Die Sperre für heute wurde noch nicht gesetzt.

Die Sperre ist eine tägliche Option: _charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>. Sobald sie gesetzt ist, werden an diesem Tag keine weiteren Benachrichtigungen für die Moderationswarteschlange ausgelöst.

Schwellenwert überschreiben:

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

Ereignis 2: Erste Spendenaktion

Wird ausgelöst, wenn eine übergeordnete Kampagne ihre erste veröffentlichte Spendenaktion erhält. Der Moment, in dem das Programm für diese übergeordnete Kampagne „lebendig wird“.

Latch: Post-Meta pro übergeordneter Kampagne _charitable_ambassadors_notif_first_fundraiser_fired. Sobald gesetzt, wird es für diese übergeordnete Kampagne nie wieder ausgelöst.

Ereignis 3: Ziel erreicht

Wird ausgelöst, wenn eine Spendenaktion zum ersten Mal 100 % ihres Ziels überschreitet. Die Prüfung erfolgt zum Zeitpunkt des Spendenabschlusses.

Latch: Post-Meta pro Spendenaktion _charitable_ambassadors_notif_goal_reached. Das Latch wird gelöscht, wenn eine Spende später zurückerstattet wird und die Spendenaktion unter das Ziel fällt. Wenn sie später erneut überschritten wird, erhalten Sie erneut eine Benachrichtigung.

Ereignis 4: Gesamtspenden-Stufe

Wird ausgelöst, wenn der gesamte von Botschaftern gesammelte Betrag auf der Website eine Stufenschwelle überschreitet. Standardstufen:

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

Jede Stufe ist ein eigenes Latch (Option _charitable_ambassadors_notif_total_raised_tier_<amount>). Das Überschreiten von 1.000 $, dann später 5.000 $ und dann später 10.000 $ löst jeweils separat aus.

Passen Sie die Stufenliste an:

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

Nachfüllen bei Aktivierung

Bei Aktivierung von Ambassadors 3.0 unterdrückt das Plugin historische Ereignisse, indem es jedes relevante Latch voreinstellt. Andernfalls würden Sie bei der ersten Aktivierung eine Flut von Benachrichtigungen „X hat Ziel erreicht“ für Spendenaktionen erhalten, die vor Jahren abgeschlossen wurden.

Das Nachfüllen:

• Stempelt _notif_first_fundraiser_fired auf jede übergeordnete Kampagne, die bereits mindestens eine veröffentlichte Spendenaktion hat.
• Stempelt _notif_goal_reached auf jede Spendenaktion, die bereits bei 100 % oder mehr liegt.
• Stempelt die entsprechende _notif_total_raised_tier_<amount> für jede bereits erreichte Stufe.

Sie sehen keine historischen Benachrichtigungen, aber neue Ereignisse ab dem Zeitpunkt der Aktivierung werden normal ausgelöst.

Tipps, die es wert sind, beachtet zu werden

Ein paar Dinge, die Ihnen helfen, das Beste aus dem Benachrichtigungsfenster herauszuholen, ohne dass es zu Lärm wird.

• Lassen Sie die Standardeinstellungen den ersten Monat lang unverändert. Sie sind so abgestimmt, dass sie selten vorkommen. Unterdrücken Sie Ereignisse nur, wenn Sie feststellen, dass eines zu oft vorkommt.
• Das Glocken-Symbol ist eine Zusammenfassung, kein Echtzeit-Stream. Benachrichtigungen bleiben bestehen, bis sie abgewiesen werden; sie laufen nicht automatisch ab.
• Verwenden Sie im Entwicklungsmodus den Master-Kill-Schalter. Sie müssen keine Updates des Glocken-Symbols sehen, während Sie an einer Anpassung arbeiten.
• Gesamtspenden-Stufen sind ein stilles Signal „Sie wachsen“. Oft die lohnendste Benachrichtigung, sie ist buchstäblich eine Bestätigung, dass das Programm funktioniert.

Entwicklerreferenz

Der Rest dieser Seite ist für Entwickler, die das Ambassadors-Benachrichtigungssystem anpassen oder erweitern.

Master-Kill-Schalter

Wenn die Benachrichtigungen des Glocken-Symbols für Ihr Programm nicht nützlich sind, deaktivieren Sie sie alle in einer Zeile:

add_filter( 'charitable_ambassadors_notifications_enabled', '__return_false' );

Dies ist global. Es unterdrückt jedes Ereignis, das Ambassadors auslöst. Eigene Benachrichtigungen von Pro (z. B. Spende erhalten) sind davon nicht betroffen.

Einzelereignis-Steuerung

Sie können einzelne Ereignisse unterdrücken, ohne die gesamte Funktion zu deaktivieren. Jedes Ereignis hat einen _should_fire_<event>-Filter:

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

Jeder wird zur Triggerzeit in einen apply_filters-Aufruf verpackt, sodass die Rückgabe von false die Benachrichtigung abkürzt, bevor sie gepostet wird.

Anpassen von Event-Inhalten

Jedes Event hat auch einen _args_<event>-Filter, der das Args-Array empfängt, bevor es an die Benachrichtigungs-API von Pro übergeben wird. Verwenden Sie diesen, um den Titel, den Link, den Text oder das Symbol zu ändern:

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

Speicher

Sperre	Schlüssel	Geltungsbereich
Moderationswarteschlange (täglich)	_charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>	Option
Erste Spendenaktion (pro Elternteil)	_charitable_ambassadors_notif_first_fundraiser_fired	Post-Meta auf Elternteil
Ziel erreicht (pro Spendenaktion)	_charitable_ambassadors_notif_goal_reached	Post-Meta auf Spendenaktion
Gesamtbetrag-Tier (pro Tier)	_charitable_ambassadors_notif_total_raised_tier_<amount>	Option

Pro API

Benachrichtigungen werden über die öffentliche API von Pro gepostet:

Charitable_Local_Notifications::add( $args );

Die Form und Speicherung der Argumente liegt bei Pro; Ambassadors ruft nur auf.

Achtung: Charitable_Local_Notifications::add() speichert Einträge als numerisch indizierte Liste, nicht als ID-gekeypte Map. Wenn Sie den zugrunde liegenden Speicher direkt abfragen, behandeln Sie ihn als Liste.

Filter

Filter	Standard	Zweck
charitable_ambassadors_notifications_enabled	wahr	Master-Kill-Schalter.
charitable_ambassadors_notifications_should_fire_<event>	wahr	Ereignisbezogene Unterdrückung.
charitable_ambassadors_notifications_args_<event>	berechnet	Ereignisbezogener Argumenten-Modifikator.
charitable_ambassadors_notifications_moderation_queue_threshold	5	Schwellenwert für ausstehende Anzahl.
charitable_ambassadors_notifications_total_raised_tiers	Array von 9	Tier-Beträge in aufsteigender Reihenfolge.

Aktionen

Aktion	Argumente	Wird ausgelöst, wenn
charitable_ambassadors_notification_fired	$event_slug, $args	Eine Benachrichtigung wurde an Pros Glockensymbol gesendet.
charitable_ambassadors_notification_suppressed	$event_slug, $reason	Eine Benachrichtigung wurde unterdrückt (Kill Switch, pro Ereignis oder Latch gehalten).

Trigger-Klasse

Charitable_Ambassadors_Notification_Triggers::get_instance();

Singleton. Alle Ereignis-Listener werden in seinem __construct() registriert. Sie können spezifische Listener per Referenz mit remove_action() entfernen, wenn Sie eine chirurgische Deaktivierung benötigen.

Testmodus-Ausschluss

Die Prüfung der Spenden-Tier-Gesamtsumme schließt Spenden aus, die mit _postmeta('test_mode') = '1' markiert sind. Der Ausschluss befindet sich in Charitable_Ambassadors_Overview_Data::get_donation_aggregates(), das der Benachrichtigungsdienst wiederverwendet.

Funktionen

Das Glockensymbol-Panel selbst wird durch Pros Standardberechtigung gesteuert. Botschafter-Benachrichtigungen erben diese Berechtigung.

Anpassungsbeispiele

Allgemeine Anpassungen. Fügen Sie eine dieser Optionen zu den functions.php Ihres Themes oder einem standortspezifischen Plugin hinzu.

Ersetzen Sie den Text „5 Spendenaktionen warten auf Überprüfung“ durch Ihre eigene Formulierung:

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

Spiegeln Sie jede Botschafter-Benachrichtigung an 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 );

Setzen Sie das „Erste Spendenaktion“-Latch für Tests zurück (Benachrichtigung erneut ausführen):

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

Unterschiedliche Tiers für zwei verschiedene Websites in einem Multisite-Netzwerk:

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

Zusammenfassung

Das deckt die Botschafter-Benachrichtigungsereignisse ab, von ihrer Auslösung bis zur Anpassung. Sie funktionieren automatisch nach der Aktivierung und erfordern keine Konfiguration, um nützlich zu sein. Wenn Sie den Moderationsschwellenwert anpassen, die Meilenstein-Tiers ändern oder Benachrichtigungen an Slack weiterleiten möchten, decken die Filter und Anpassungsbeispiele oben all diese Fälle ab.

Wenn Sie Fragen zu den Benachrichtigungsereignissen oder der Pro-Benachrichtigungs-API haben, hilft Ihnen unser Support-Team gerne weiter.

Das könnten Sie auch interessieren

Diese Dokumentation behandelt die Funktionen, die am engsten mit den Ereignissen verbunden sind, die Botschafter-Benachrichtigungen auslösen.

• Übersichts-Dashboard – das Ereignis für die Gesamtsumme der gesammelten Spenden verwendet die Datenklasse „Overview“, und im Dashboard sehen Sie Ihre Zahlen auf Programmebene.
• Moderation – wohin Sie die Benachrichtigung über den Zustand der Moderationswarteschlange führt, wenn die Anzahl der ausstehenden Elemente den Schwellenwert überschreitet.
• E-Mail-Vorlagen – die zugehörige Transaktions-E-Mail-Oberfläche für Botschafter-Benachrichtigungen.
• Hooks & Filter in Botschaftern – die vollständige Referenz für Filter und Aktionen des gesamten Botschafter-Add-ons.