Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

L'Aperçu est l'écran d'accueil de votre programme de collecte de fonds pair-à-pair. C'est la première page que vous verrez en ouvrant Ambassadeurs dans votre administration WordPress, et elle est conçue pour que vous puissiez répondre aux questions que tout gestionnaire de programme se pose chaque matin :

• Combien avons-nous collecté ce mois-ci ?
• Qui est notre meilleur collecteur de fonds actuellement ?
• De nouveaux ambassadeurs s'inscrivent, ou la croissance a stagné ?
• Quelles campagnes font leur part ?

Au lieu de générer des rapports ou de rassembler des listes de dons, l'Aperçu montre tout en un coup d'œil.

Quand l'utiliser

Quelques moments courants où l'Aperçu justifie son utilité :

• Point de situation du lundi matin : sélectionnez « 7 derniers jours » et parcourez les indicateurs clés pour voir comment s'est déroulé le week-end.
• Rapport mensuel du conseil : passez à « Mois dernier », cliquez sur Imprimer le résumé, et vous obtenez un aperçu d'une page pour votre réunion.
• Bilan de fin de campagne : sélectionnez une plage personnalisée couvrant la période de la campagne et téléchargez des CSV pour chaque section.
• Repérer une cause en difficulté : le graphique en anneau des meilleures campagnes parentales met en évidence la concentration des causes ; la liste des meilleurs ambassadeurs montre qui vous pourriez remercier publiquement pour maintenir l'élan.

Trouver l'Aperçu

Une fois Charitable Ambassadeurs installé et activé, vous trouverez l'Aperçu à l'adresse suivante :

Admin WordPress » Charitable » Ambassadeurs » Aperçu

C'est l'onglet le plus à gauche et la page d'atterrissage par défaut pour la zone Ambassadeurs, donc la plupart du temps, vous n'avez rien à cliquer pour y accéder.

Les trois choses que vous ferez le plus souvent

1. Choisir une plage de dates

Tout sur l'Aperçu respecte la plage de dates sélectionnée en haut à droite de la page. Cliquez sur le champ de date et choisissez parmi les préréglages :

• 7 derniers jours, 14 derniers jours, 30 derniers jours (par défaut), 90 derniers jours
• Ce mois-ci, Mois dernier, Cette année
• Toute la durée de vie – tous les dons depuis le début
• Personnalisé – ouvre un calendrier pour que vous puissiez choisir n'importe quelle paire de dates

Quelle que soit la plage que vous choisissez, elle est mémorisée juste pour vous – la prochaine fois que vous visiterez, la page se chargera automatiquement dans la même plage. Si vous partagez un identifiant avec un collègue, il verra son propre défaut.

2. Lire les chiffres clés

Les six grandes tuiles en haut sont le titre de votre programme :

Tuile	Ce que cela signifie en langage clair
Collecté	Montant total des dons reçus via les campagnes d'ambassadeurs pendant la période que vous avez choisie.
Dons	Nombre de cadeaux reçus, chaque don étant compté comme un (même plusieurs cadeaux de la même personne).
Donateurs	Combien de personnes uniques ont donné. Quelqu'un qui a donné deux fois compte pour une.
Collectes actives	Combien de collecteurs individuels ont reçu au moins un don dans la période. La ligne en dessous (« 17 sur 31 ambassadeurs vérifiés ») concerne la durée de vie, vous pouvez donc voir quelle proportion de votre effectif est validée.
Nouveaux ambassadeurs	Combien de personnes ont créé leur première collecte pendant la période – votre indicateur de croissance.
Don moyen	Le montant moyen en dollars par don. Utile pour repérer les changements dans le comportement des donateurs.

La petite flèche à côté de chaque nombre le compare à la période précédente de même durée. Flèche verte vers le haut = croissance ; flèche rouge vers le bas = déclin. Si la valeur actuelle ou précédente est zéro, la flèche est masquée afin que vous ne voyiez jamais un « -100 % à partir de 0 $ » dénué de sens.

3. Repérez vos meilleurs performeurs

Sous les tuiles principales, vous trouverez des classements pour les collecteurs, les ambassadeurs et les campagnes mères :

• Meilleurs collecteurs – les 5 collecteurs individuels qui ont rapporté le plus d'argent pendant la période.
• Meilleurs ambassadeurs – les 5 personnes (auteurs de campagne) qui ont personnellement collecté le plus, même s'ils ont géré plusieurs collectes.

• Meilleures campagnes mères – un graphique circulaire indiquant quelles causes attirent le plus. Utile pour repérer la concentration des causes (« oh, 70 % de notre argent va au marathon – nous devrions mobiliser du soutien pour les autres causes aussi »).

Cliquez sur n'importe quel nom dans le widget Meilleurs ambassadeurs pour ouvrir leur profil complet dans le Répertoire.

Observer l'évolution dans le temps

Le graphique Dons dans le temps au milieu de la page montre votre vélocité de collecte :

Deux couches se superposent :

• Vert représente les dons faits directement à vos campagnes mères (causes).
• Orange représente les dons faits aux collecteurs individuels en dessous.

Plus la zone orange est grande par rapport au vert, plus vos collecteurs stimulent le programme plutôt que les dons directs. C'est généralement le signe d'un effort de pair-à-pair sain.

Les compartiments en bas changent automatiquement en fonction de la période que vous avez choisie :

• Choisissez une période allant jusqu'à 90 jours, et vous verrez des barres jour par jour.
• Choisissez un trimestre ou une année, et le graphique passe aux semaines.
• Choisissez « Durée de vie » ou une période de plusieurs années, et vous obtiendrez des compartiments mensuels.

Cliquez sur Télécharger le CSV en haut à droite du graphique pour exporter les données groupées – pratique si vous voulez les insérer dans une feuille de calcul pour votre présentation au conseil.

Suivi de l'activité de recrutement

Si vous avez activé les Invitations – la fonctionnalité qui permet à vos ambassadeurs existants d'en recruter de nouveaux – vous verrez un widget de recrutement plus bas sur la page.

Il indique combien de nouveaux ambassadeurs sont arrivés via des liens d'invitation personnels, ventilés par statut (Approuvé, En attente, Rejeté), avec un graphique de la vélocité de recrutement et un classement de vos meilleurs recruteurs. Si vous n'avez pas encore activé les Invitations, vous verrez simplement une carte d'état vide avec un lien pour l'activer.

L'activité la plus récente

Faites défiler vers le bas et vous trouverez Dons récents – les huit dons les plus récents de toutes les campagnes d'ambassadeurs sur votre site, avec les avatars des donateurs et des horodatages « il y a 5 minutes ». Contrairement à tout le reste sur la page, cette liste ignore la plage de dates que vous avez choisie en haut – elle affiche toujours l'activité la plus récente afin que vous puissiez voir ce qui se passe en ce moment.

Exportation des données

La plupart des sections de la Vue d'ensemble ont un bouton Télécharger CSV dans leur en-tête :

• Section KPI : CSV des six chiffres clés + tendances
• Dons au fil du temps : totaux par catégorie
• Meilleurs collecteurs de fonds, meilleurs ambassadeurs, meilleurs parents : listes classées
• Recrutement : le journal complet des recrutements pour la période

Ce sont des fichiers CSV purs (chaque cellule est assainie pour empêcher l'injection de formules Excel), limités à 10 000 lignes afin que vous puissiez les ouvrir en toute sécurité dans n'importe quel programme tableur.

Impression d'une page unique

Cliquez sur l'icône de l'imprimante à côté du sélecteur de plage de dates, et votre navigateur ouvrira un aperçu d'impression qui supprimera la barre latérale d'administration, votre autre barre d'administration et l'en-tête de la page – ne laissant qu'une page unique et propre que vous pouvez enregistrer en PDF pour les réunions du conseil d'administration ou partager avec votre directeur.

Que faire si vous voyez que tout est à zéro

Une Vue d'ensemble vide signifie généralement l'une des trois choses suivantes :

Ce que vous voyez	Ce qui se passe	Comment le réparer
Une carte « Démarrer » avec une liste de vos campagnes	Vous n'avez encore activé le peer-to-peer sur aucune campagne.	Cliquez sur Activer le Peer-to-Peer sur une campagne – vous choisissez la cause pour laquelle vos ambassadeurs collecteront des fonds.
Une bannière indiquant « aucun collecteur de fonds pour le moment »	Vous avez une campagne activée pour le peer-to-peer, mais aucun ambassadeur ne s'est encore inscrit pour collecter des fonds.	Partagez l'URL de soumission de cette campagne avec des ambassadeurs potentiels, ou configurez des Invitations.
Graphiques squelettes avec « Aucune donation pour le moment »	Vous avez des collecteurs de fonds, mais aucune donation n'est entrée pendant la plage de dates que vous avez choisie.	Essayez de passer à « Durée de vie » – vos données sont peut-être simplement plus anciennes que la période sélectionnée.

Conseils

• Les tuiles, graphiques et listes des KPI sont mis en cache pendant 5 minutes pour que la page reste réactive. Si vous venez d'effectuer une modification et que vous souhaitez la voir immédiatement, cliquez sur l'icône de rafraîchissement circulaire à côté du sélecteur de date.
• Survolez les petites flèches de tendance à côté de chaque KPI pour voir les chiffres exacts de la période précédente.
• La tuile « Approbations en attente » n'apparaît que lorsque vous utilisez l'Approbation manuelle et qu'au moins un collecteur de fonds attend votre examen. Cliquez dessus pour accéder directement à la file d'attente de modération.

Référence développeur

Le reste de cette page est destiné aux développeurs qui personnalisent la Vue d'ensemble ou qui l'utilisent comme base.

Filtres

Filtre	Défaut	Objectif
charitable_ambassadors_overview_top_fundraisers_limit	5	Nombre de collecteurs de fonds dans le tableau des meilleurs collecteurs de fonds (1-50).
ambassadeurs_bienfaiteurs_aperçu_limite_hauts_ambassadeurs	5	Nombre d'ambassadeurs dans le widget Top Ambassadeurs.
ambassadeurs_bienfaiteurs_aperçu_parents_hauts_min_parents	2	Nombre minimum de parents avant que le graphique circulaire ne s'affiche. En dessous de ce seuil, le graphique circulaire affiche un squelette.
ambassadeurs_bienfaiteurs_aperçu_inclure_ambassadeurs_inactifs	vrai	Inclure les ambassadeurs avec zéro don dans Top Ambassadeurs. Définissez sur false pour utiliser une jointure interne au lieu d'une jointure externe de la table des dons.
ambassadeurs_bienfaiteurs_aperçu_titre_temporaire	5 * MINUTE_EN_SECONDES	Durée de vie (TTL) pour le cache transitoire par section.
ambassadeurs_bienfaiteurs_aperçu_plages_predefinies	tableau de 9 préréglages	Remplacez la liste des préréglages de plage de dates affichée dans le sélecteur.
charitable_ambassadors_overview_csv_max_rows	10000	Limite maximale de lignes pour chaque exportation CSV.
ambassadeurs_bienfaiteurs_aperçu_accueil_active	vrai	Retournez false pour supprimer l'avis de bienvenue sur l'ensemble du site.
ambassadeurs_bienfaiteurs_aperçu_accueil_url_docs	URL de documentation/charitable-ambassadors-addon-update	Remplacez l'URL vers laquelle le message de bienvenue pointe.

Actions

Action	Args	Se déclenche lorsque
ambassadeurs_bienfaiteurs_aperçu_avant_carres_kpi	–	Juste avant l'affichage des six tuiles KPI. Utilisez pour injecter une tuile personnalisée ou une bannière.
ambassadeurs_bienfaiteurs_aperçu_apres_dons_recents	–	Après le widget Dons récents. Utilisez pour un bloc supplémentaire en bas de page.

Points de terminaison AJAX

Les quatre sont uniquement wp_ajax_ (pas de nopriv_), action nonce charitable_ambassadors_overview, capacité manage_charitable_settings.

Action	Objectif
ambassadeurs_bienfaiteurs_aperçu_graphique_principal	Retourne la série Dons au fil du temps pour la plage active. Appelée une fois par chargement de page, après le premier affichage.
ambassadeurs_bienfaiteurs_aperçu_enregistrer_plage	Conserve la plage de dates choisie par l'utilisateur dans user_meta afin qu'elle se charge lors de la prochaine visite.
ambassadeurs_bienfaiteurs_aperçu_activer_p2p	Active/désactive le méta _campaign_supports_child_campaigns d'une seule campagne à partir du sélecteur en ligne de l'état vide sans parents. Limité par current_user_can( 'edit_post', $campaign_id ) par ligne.
ambassadeurs_bienfaiteurs_aperçu_ignorer_accueil	Indicateur de rejet par utilisateur pour la notification de bienvenue. Stocké dans user_meta('charitable_ambassadors_overview_welcome_dismissed').

Classe de données

Charitable_Ambassadors_Overview_Data (singleton, get_instance()) est la source de données pour chaque section de l'aperçu. Les méthodes publiques sont :

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

Les arguments de date sont des chaînes de date/heure MySQL ('Y-m-d H:i:s'). Toutes les méthodes mettent en cache les résultats dans des transitoires indexés par section + plage de dates.

Contournement du cache

Le cache transitoire est automatiquement contourné lorsque :

• Un don est enregistré, remboursé ou mis à la corbeille (charitable_donation_saved, charitable_donation_refunded).
• Une cagnotte enfant passe de ou vers publish (transition_post_status).
• La méta _campaign_supports_child_campaigns d'une campagne est ajoutée, mise à jour ou supprimée.

L'appel de contournement exécute Charitable_Ambassadors_Overview_Data::bust_cache(), qui :

1. SUPPRIME chaque ligne _transient_charitable_ambassadors_overview_% de wp_options.
2. Évacue la superclé alloptions et les entrées par ligne correspondantes du cache d'objets WP.

La suppression SQL brute est intentionnelle – $wpdb->prepare() avec des jokers % finaux a été cassé par le renforcement des espaces réservés de WP 6.2, nous utilisons donc une clause LIKE littérale à l'intérieur d'un $wpdb->query().

Pour vider manuellement le cache à des fins de débogage, visitez ?charitable_ambassadors_clear_overview_cache=1 en étant connecté en tant qu'administrateur.

Exclusion du mode test

Chaque agrégat de dons exclut les dons marqués avec _postmeta('test_mode') = '1'. L'exclusion se trouve dans get_donation_aggregates() et se propage au graphique principal et aux exportations CSV. Basculez le mode test de Charitable via Charitable » Paramètres » Avancé » Mode Test.

Exportations CSV

Formulaire POST vers admin-post.php?action=charitable_ambassadors_overview_csv, action nonce charitable_ambassadors_overview_csv, capacité manage_charitable_settings. L'argument de requête section sélectionne quel jeu de données :

• résumé kpi
• dons_au_fil_du_temps
• meilleurs_collecteurs_de_fonds
• meilleurs_ambassadeurs
• meilleurs_parents
• journal_de_recrutement
• meilleurs_recruteurs_de_recrutement

Les noms de fichiers suivent le modèle ambassadeurs-<section>-<début>-à-<fin>.csv. Chaque cellule est traitée via Charitable_Ambassadors_Overview_CSV::neutralize_csv_cell() qui ajoute une apostrophe ' en préfixe à toute chaîne commençant par =, +, -, @, tabulation ou CR (défense contre l'injection de formules Excel recommandée par l'OWASP).

Capacités

Le seul portail de capacité est manage_charitable_settings. Ceci est accordé aux Administrateurs par défaut. Pour accorder l'accès à l'Aperçu à un rôle non-administrateur sans accorder d'autres accès aux paramètres Charitable, ajoutez la capacité à ce rôle.

Message de bienvenue

Une carte avec une bordure bleue en haut de l'Aperçu renvoie aux notes de mise à jour du module complémentaire 3.0. Elle est dismissible par utilisateur, persistée via le point de terminaison AJAX charitable_ambassadors_overview_dismiss_welcome dans user_meta('charitable_ambassadors_overview_welcome_dismissed').

Pour supprimer le message sur l'ensemble du site, quel que soit l'état de rejet :

add_filter( 'charitable_ambassadors_overview_welcome_enabled', '__return_false' );

Exemples de personnalisation

Quelques petits changements qui reviennent souvent. Insérez l'un de ceux-ci dans le fichier functions.php de votre thème ou dans un plugin d'extraits de code.

Afficher 10 collecteurs de fonds dans la liste des meilleurs collecteurs de fonds au lieu de 5 :

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

Masquer les ambassadeurs n'ayant rien collecté du widget des meilleurs ambassadeurs :

add_filter( 'charitable_ambassadors_overview_include_inactive_ambassadors', '__return_false' );

Mettre en cache pendant 30 minutes au lieu de 5 :

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

Remplacer le message de bienvenue par un lien vers votre propre page d'intégration :

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

Ajouter une bannière personnalisée au-dessus des tuiles KPI :

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

Connexes

• Assistant de configuration – le flux d'intégration en trois étapes qui structure votre premier programme pair-à-pair.
• Modération – approuver, rejeter et demander des modifications sur les soumissions des collecteurs de fonds.
• Annuaire – votre liste complète d'ambassadeurs avec profils, dons et historique de recrutement.
• Invitations – le système de recrutement qui alimente le widget de recrutement ci-dessus.
• Hooks & filtres dans Ambassadors – la référence complète des filtres et actions.