Requis : Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+
Vos ambassadeurs ne font pas de collecte de fonds dans le vide. Ils écrivent des articles de blog, partagent des histoires sur des sites partenaires et créent des pages de destination sur des plateformes qui n'ont rien à voir avec votre installation WordPress. Le widget d'intégration leur donne un moyen d'intégrer leur collecte de fonds dans tous ces endroits.
Le Widget d'intégration permet à vos ambassadeurs de coller un petit extrait HTML sur n'importe quel site externe : un article de blog, une page de destination, un site partenaire et un article Medium. Il affiche la barre de progression en direct de leur collecte de fonds et le bouton de don sans iframe, sans installation et sans framework JavaScript requis. Le widget récupère les données en direct de l'API REST de votre site et reste synchronisé au fur et à mesure que les dons arrivent.
Il transforme « partager ce lien » en « intégrer ce widget », ce qui signifie que votre collecte de fonds apparaît dans le contexte réel où les gens lisent, au lieu de leur demander de cliquer sur un site distinct.
Quand l'utiliser
Le widget d'intégration ouvre de nombreuses portes aux ambassadeurs qui font activement la promotion de leur collecte de fonds au-delà de votre site. Voici les situations les plus courantes :
- Articles de blog d'ambassadeurs : votre ambassadeur écrit sur sa collecte de fonds sur son blog personnel. Insérez le widget dans l'article, et les lecteurs peuvent faire un don sans quitter la page.
- Sites partenaires et médiatiques : un site d'actualités local couvre votre événement. Ils intègrent le widget afin que les lecteurs puissent faire un don en ligne pendant qu'ils lisent l'histoire.
- Pages de destination sur d'autres plateformes : votre équipe marketing crée une page de destination sur Webflow, Framer ou Squarespace. Collez l'extrait, et vous obtenez un widget en direct sans plugin requis.
- Tableaux de bord internes : la direction souhaite une vue en temps réel de la collecte de fonds du gala sur l'intranet de l'entreprise. Intégrez-le, et il se met à jour automatiquement.
Comment y accéder
Allez dans Caritatif » Ambassadeurs » Divers » Widget d'intégration. Le widget est désactivé par défaut.
Activez Activer le widget d'intégration, configurez les paramètres par défaut, et la vignette du widget d'intégration apparaîtra dans la fenêtre contextuelle de partage sur chaque page de collecte de fonds.
Les paramètres
| Paramètre | Défaut | Effet |
|---|---|---|
| Activer le widget d'intégration | Désactivé | Interrupteur principal. Tant qu'il n'est pas activé, la vignette du widget d'intégration est masquée dans toutes les fenêtres contextuelles de partage. |
| Taille par défaut de l'extrait | Compact (320×500) | La taille que la fenêtre modale propose en premier. Compact convient bien aux barres latérales et aux colonnes étroites. Large (600×320) convient aux blocs pleine largeur. |
| Thème par défaut de l'extrait | Clair | Clair ou Sombre. Les ambassadeurs peuvent remplacer cela par intégration dans la fenêtre modale. |
| Origines autorisées CORS | * (toutes origines) | Une origine par ligne, ou * pour autoriser n'importe laquelle. Le point de terminaison REST applique cet en-tête. |
Les paramètres par défaut sont ceux avec lesquels le générateur d'extraits commence. Les ambassadeurs peuvent modifier la taille ou le thème dans la fenêtre modale avant de copier, donc ce sont des points de départ plutôt que des limites strictes.
Le flux utilisateur
Depuis n'importe quelle page de collecte de fonds, un visiteur ou l'ambassadeur lui-même clique sur le bouton Partager et choisit Intégrer le widget. La fenêtre modale qui s'ouvre contient trois sections :
- Aperçu en direct : un rendu en temps réel de l'apparence du widget à la taille et au thème choisis.
- Options de taille et de thème : basculez entre Compact et Large, ou Clair et Sombre.
- Extrait : une zone de texte copiable avec le code HTML exact. Un bouton Copier l'extrait et il est prêt à être collé.
L'extrait ressemble à ceci :
<div class="charitable-embed-widget"
data-fundraiser-id="123"
data-size="compact"
data-theme="light"></div>
<script src="https://yoursite.com/wp-content/plugins/charitable-ambassadors/assets/js/charitable-ambassadors-embed-widget.js"
async></script>Collez cela partout où les balises <script> sont autorisées : un article WordPress, un article Medium, un bloc d'intégration Webflow. Le widget se rend au chargement de la page et interroge les mises à jour automatiquement.
Ce qui s'affiche sur le site de destination
Le widget montre tout ce dont un visiteur a besoin pour comprendre et soutenir la collecte de fonds, sans quitter la page sur laquelle il se trouve :
- Image mise en avant (petite miniature en haut en mode Compact, image principale alignée à gauche en mode Large).
- Titre et nom de l'ambassadeur.
- Montant collecté actuel et objectif avec une barre de progression.
- Nombre de donateurs.
- Un bouton Faire un don qui ouvre la page de collecte de fonds dans un nouvel onglet, de sorte que le flux de dons réel utilise votre formulaire en direct plutôt qu'un mini formulaire à l'intérieur du widget.
Les mises à jour en direct se produisent toutes les 30 secondes via le point de terminaison REST, de sorte que les chiffres restent précis au fur et à mesure que les dons arrivent.
Configuration CORS
Étant donné que le widget se charge sur des sites tiers, le point de terminaison REST nécessite des en-têtes CORS. Le caractère * par défaut autorise n'importe quelle origine, ce qui est pratique pour commencer. Si votre politique de sécurité exige une liste d'autorisation explicite, remplacez * par une origine par ligne :
https://partner.example.com
https://blog.yoursite.com
https://medium.comLe point de terminaison émet un en-tête Access-Control-Allow-Origin correspondant à l'origine de la requête lorsqu'il trouve une correspondance dans la liste.
Lorsque le widget ne peut pas s'afficher
Trois situations peuvent empêcher l'affichage du widget. Dans chaque cas, le mécanisme de repli est conçu de manière à ce que la page hôte ne soit jamais interrompue par une mauvaise intégration.
| État | Ce qui s'affiche |
|---|---|
| Collecte de fonds inexistante | Un espace réservé « Collecte de fonds indisponible ». La console du navigateur enregistre une erreur avec l'ID de la collecte de fonds. |
| Collecte de fonds non publiée | « Collecte de fonds indisponible » – identique à ci-dessus. La vérification de la visibilité publique correspond à la page publique de la collecte de fonds. |
| CORS refusé | Le conteneur du widget reste vide. La console du navigateur affiche l'erreur CORS. La page hôte elle-même n'est pas affectée. |
Conseils à garder à l'esprit
Quelques éléments qui améliorent le fonctionnement du widget d'intégration en pratique.
- Utilisez Large pour les sections principales, Compact pour les barres latérales. Large mesure 600 × 320 et fonctionne bien dans un emplacement de contenu mis en avant. Compact mesure 320 × 500 et s'intègre naturellement dans une barre latérale verticale ou une colonne étroite.
- Adaptez le thème au site hôte. Les intégrations sombres sont superbes sur les blogs plus sombres et le mode nuit de Medium. Clair fonctionne sur la plupart des sites marketing et éditoriaux.
- Verrouillez le CORS avant un audit de sécurité. Le caractère
*par défaut accepte les intégrations de n'importe quelle origine. Si cela est important pour votre programme, ajoutez une liste d'autorisation explicite avant de passer en production. - Le snippet vit éternellement une fois qu’il est collé. Lorsqu’un ambassadeur copie le snippet sur un site externe, ce site continue de récupérer des données en direct de votre API REST indéfiniment. Si vous devez un jour retirer un élément intégré, retirez la campagne de la publication.
Référence développeur
Le reste de cette page est destiné aux développeurs qui personnalisent le widget d’intégration.
Stockage des paramètres
charitable_settings > ambassadors > embed_widget_enabled
charitable_settings > ambassadors > embed_widget_default_size # 'compact' | 'wide'
charitable_settings > ambassadors > embed_widget_default_theme # 'light' | 'dark'
charitable_settings > ambassadors > embed_widget_cors_origins # newline-separated or '*'Point d'accès REST
GET /wp-json/charitable-ambassadors/v1/embed-widget/<fundraiser_id>Retourne du JSON :
{
"id": 123,
"title": "Sarah's Marathon Run",
"permalink": "https://yoursite.com/fundraisers/sarahs-marathon-run/",
"image_url": "https://yoursite.com/wp-content/uploads/2026/05/hero.jpg",
"raised": 12450,
"goal": 50000,
"donor_count": 87,
"ambassador_name": "Sarah Chen",
"currency": "USD"
}Capacités : public, aucune authentification requise, car le widget doit se charger sur des sites externes. CORS est contrôlé par le filtre charitable_ambassadors_embed_widget_cors_origins, qui lit par défaut le paramètre Origines autorisées CORS.
Classes
| Classe | Fichier | Rôle |
|---|---|---|
Charitable_Ambassadors_Embed_Widget_Rest | includes/embed-widget/class-charitable-ambassadors-embed-widget-rest.php | Enregistrement de la route REST et gestionnaire CORS. |
Charitable_Ambassadors_Embed_Widget_Renderer | includes/embed-widget/class-charitable-ambassadors-embed-widget-renderer.php | Rendu côté serveur et HTML de la modale. |
Filtres
| Filtre | Défaut | Objectif |
|---|---|---|
charitable_ambassadors_embed_widget_enabled | valeur du paramètre | Forcer la fonctionnalité activée ou désactivée. |
charitable_ambassadors_embed_widget_cors_origins | valeur du paramètre sous forme de tableau | La liste des origines autorisées pour le point de terminaison REST. Utilisez [ '*' ] pour n’importe laquelle. |
charitable_ambassadors_embed_widget_default_size | valeur du paramètre | Remplacer la taille par défaut. |
charitable_ambassadors_embed_widget_default_theme | valeur du paramètre | Remplacer le thème par défaut. |
charitable_ambassadors_embed_widget_response | calculé | Filtrer la charge utile de la réponse REST. Reçoit ($payload, $fundraiser_id). |
charitable_ambassadors_embed_widget_docs_url | cette page | Remplacer l’URL de la documentation vers laquelle le lien « Comment intégrer » pointe. |
Actions
| Action | Args | Se déclenche lorsque |
|---|---|---|
charitable_ambassadors_embed_widget_rendered | $fundraiser_id, $size, $theme | Le rendu côté serveur est terminé. |
API JS
Le script du widget expose un petit objet global que vous pouvez appeler depuis le JS de la page hôte pour forcer une actualisation des données en dehors de l’intervalle d’interrogation normal :
window.charitableEmbedWidget.refresh( containerEl );Capacités
Point de terminaison REST : lecture publique. Les paramètres d’administration nécessitent manage_charitable_settings.
Exemples de personnalisation
Restreindre CORS à deux origines approuvées :
add_filter( 'charitable_ambassadors_embed_widget_cors_origins', function () {
return [ 'https://partner.example.com', 'https://blog.yoursite.com' ];
} );Forcer toujours le thème sombre, quel que soit le choix de l’ambassadeur :
add_filter( 'charitable_ambassadors_embed_widget_default_theme', function () {
return 'dark';
} );Ajouter un champ personnalisé à la réponse REST (par exemple, la biographie de l’ambassadeur) :
add_filter( 'charitable_ambassadors_embed_widget_response', function ( $payload, $fundraiser_id ) {
$author_id = (int) get_post_field( 'post_author', $fundraiser_id );
$payload['ambassador_bio'] = get_user_meta( $author_id, 'description', true );
return $payload;
}, 10, 2 );Masquer la vignette du widget d’intégration du pop-over de partage pour des rôles utilisateur spécifiques :
add_filter( 'charitable_ambassadors_embed_widget_enabled', function ( $enabled ) {
if ( ! current_user_can( 'edit_posts' ) ) {
return false;
}
return $enabled;
} );En résumé
Cela couvre le widget d’intégration, de la configuration à la personnalisation. Une fois que vous l’activez, vos ambassadeurs peuvent promouvoir leurs collectes de fonds n’importe où sur le Web et maintenir l’expérience de don à jour et actuelle sans aucun travail supplémentaire de votre part. Activez-le, définissez votre politique CORS et laissez vos ambassadeurs faire le reste.
Si vous avez des questions sur la configuration CORS ou quoi que ce soit d’autre, notre équipe de support est là pour vous aider.
Vous pourriez aussi vouloir lire
Ce sont les documents les plus étroitement liés au widget d’intégration et aux fonctionnalités avec lesquelles il fonctionne.
- Réseaux de partage – le pop-over de partage où la vignette du widget d’intégration se trouve à côté des boutons de réseau social.
- Codes QR – une autre vignette de pop-over de partage qui offre aux ambassadeurs une manière différente de partager leur collecte de fonds.
- Page de collecte de fonds – la page vers laquelle le bouton « Faire un don » du widget renvoie.
- Hooks & filtres dans Ambassadeurs – la référence complète pour les développeurs.
