Erfordert: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+
Ihre Botschafter sammeln keine Spenden im luftleeren Raum. Sie schreiben Blogbeiträge, teilen Geschichten auf Partnerseiten und erstellen Landingpages auf Plattformen, die nichts mit Ihrer WordPress-Installation zu tun haben. Das Embed Widget gibt ihnen die Möglichkeit, ihre Spendenaktion an all diese Orte zu bringen.
Das Embed Widget ermöglicht es Ihren Botschaftern, einen kleinen HTML-Schnipsel auf jeder externen Seite einzufügen: einen Blogbeitrag, eine Landingpage, eine Partnerseite und einen Medium-Artikel. Es zeigt den Live-Fortschrittsbalken und die Spenden-Schaltfläche ihrer Spendenaktion ohne iframe, ohne Installation und ohne JavaScript-Framework an. Das Widget ruft Live-Daten von der REST-API Ihrer Website ab und bleibt synchron, während Spenden eingehen.
Es verwandelt „diesen Link teilen“ in „dieses Widget einbetten“, was bedeutet, dass Ihre Spendenaktion im tatsächlichen Kontext erscheint, in dem die Leute lesen, anstatt sie aufzufordern, auf eine separate Website zu klicken.
Wann Sie es verwenden würden
Das Embed Widget eröffnet viele Türen für Botschafter, die ihre Spendenaktion aktiv über Ihre Website hinaus bewerben. Hier sind die häufigsten Situationen:
- Botschafter-Blogbeiträge: Ihr Botschafter schreibt über seine Spendenaktion in seinem persönlichen Blog. Fügen Sie das Widget in den Beitrag ein, und die Leser können spenden, ohne die Seite zu verlassen.
- Partner- und Medienseiten: Eine lokale Nachrichtenseite berichtet über Ihre Veranstaltung. Sie betten das Widget ein, damit die Leser inline spenden können, während sie die Geschichte lesen.
- Landingpages auf anderen Plattformen: Ihr Marketingteam erstellt eine Landingpage auf Webflow, Framer oder Squarespace. Fügen Sie den Schnipsel ein, und Sie erhalten ein Live-Widget ohne erforderliches Plugin.
- Interne Dashboards: Die Führung möchte eine Echtzeitansicht der Gala-Spendenaktion im Intranet des Unternehmens. Betten Sie es ein, und es wird automatisch aktualisiert.
So gelangen Sie dorthin
Gehen Sie zu Charitable » Botschafter » Diverses » Embed Widget. Das Widget ist standardmäßig deaktiviert.
Aktivieren Sie Embed Widget aktivieren, konfigurieren Sie die Standardeinstellungen, und die Kachel „Embed Widget“ wird im Share-Popover jeder Spendenaktionsseite angezeigt.
Die Einstellungen
| Einstellung | Standard | Auswirkung |
|---|---|---|
| Embed Widget aktivieren | Aus | Hauptschalter. Solange er nicht aktiviert ist, ist die Kachel „Embed Widget“ aus jedem Share-Popover ausgeblendet. |
| Standard-Snippet-Größe | Kompakt (320×500) | Welche Größe das Modal zuerst anbietet. Kompakt eignet sich gut für Seitenleisten und schmale Spalten. Breit (600×320) passt gut zu Vollbild-Hero-Blöcken. |
| Standard-Snippet-Thema | Hell | Hell oder Dunkel. Botschafter können dies pro Einbettung im Modal überschreiben. |
| CORS-zugelassene Ursprünge | * (alle Ursprünge) | Ein Ursprung pro Zeile oder *, um jeden zuzulassen. Der REST-Endpunkt erzwingt diesen Header. |
Die Standardwerte sind die Ausgangspunkte des Snippet-Builders. Botschafter können die Größe oder das Thema im Modal ändern, bevor sie es kopieren. Dies sind also Ausgangspunkte und keine festen Grenzen.
Der Benutzerfluss
Von jeder Spendenaktion-Seite klickt ein Besucher oder der Botschafter selbst auf die Schaltfläche Teilen und wählt Widget einbetten. Das sich öffnende Modal hat drei Abschnitte:
- Live-Vorschau: eine Echtzeit-Darstellung, wie das Widget bei der gewählten Größe und dem gewählten Thema aussehen wird.
- Größen- und Themenumschalter: wechseln Sie zwischen Kompakt und Breit oder Hell und Dunkel.
- Snippet: ein kopierbares Textfeld mit dem genauen HTML. Ein Button Kopieren und es ist bereit zum Einfügen.
Das Snippet sieht ungefähr so aus:
<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>Fügen Sie dies überall ein, wo <script>-Tags erlaubt sind: ein WordPress-Beitrag, ein Medium-Artikel, ein Webflow-Einbettungsblock. Das Widget wird beim Laden der Seite gerendert und fragt automatisch nach Updates.
Was auf der Zielseite gerendert wird
Das Widget zeigt alles, was ein Besucher benötigt, um die Spendenaktion zu verstehen und zu unterstützen, ohne die Seite zu verlassen, auf der er sich befindet:
- Hervorgehobenes Bild (kleine Miniaturansicht oben im Kompakt-Modus, links ausgerichtetes Hero-Bild im Breit-Modus).
- Titel und Name des Botschafters.
- Aktuell gesammelter Betrag und Ziel mit Fortschrittsbalken.
- Anzahl der Spender.
- Eine Spenden-Schaltfläche, die die Spendenaktionsseite in einem neuen Tab öffnet, sodass der eigentliche Spendenfluss Ihr Live-Formular und nicht ein Mini-Formular innerhalb des Widgets verwendet.
Live-Updates erfolgen alle 30 Sekunden über den REST-Endpunkt, sodass die Zahlen genau bleiben, wenn Spenden eingehen.
CORS-Konfiguration
Da das Widget auf Websites Dritter geladen wird, benötigt der REST-Endpunkt CORS-Header. Der Standardwert * erlaubt jeden Ursprung, was praktisch für den Einstieg ist. Wenn Ihre Sicherheitsrichtlinie eine explizite Zulassungsliste erfordert, ersetzen Sie * durch einen Ursprung pro Zeile:
https://partner.example.com
https://blog.yoursite.com
https://medium.comDer Endpunkt gibt einen Access-Control-Allow-Origin-Header aus, der mit dem Origin der Anfrage übereinstimmt, wenn er eine Übereinstimmung in der Liste findet.
Wenn das Widget nicht gerendert werden kann
Drei Situationen können verhindern, dass das Widget angezeigt wird. In jedem Fall ist die Fallback-Lösung so konzipiert, dass die Host-Seite niemals durch eine fehlerhafte Einbettung beeinträchtigt wird.
| Status | Was gerendert wird |
|---|---|
| Spendenaktion existiert nicht | Ein Platzhalter „Spendenaktion nicht verfügbar“. Die Browserkonsole protokolliert einen Fehler mit der Spendenaktions-ID. |
| Spendenaktion ist nicht veröffentlicht | „Spendenaktion nicht verfügbar“ – wie oben. Die Prüfung der öffentlichen Sichtbarkeit entspricht der öffentlichen Spendenaktionsseite. |
| CORS verweigert | Der Widget-Container bleibt leer. Die Browserkonsole zeigt den CORS-Fehler an. Die Host-Seite selbst ist nicht betroffen. |
Tipps, die es wert sind, beachtet zu werden
Ein paar Dinge, die das Einbettungs-Widget in der Praxis besser funktionieren lassen.
- Verwenden Sie Breit für Hero-Bereiche, Kompakt für Seitenleisten. Breit ist 600×320 und funktioniert gut in einem hervorgehobenen Inhaltsbereich. Kompakt ist 320×500 und passt natürlich in eine vertikale Seitenleiste oder eine schmale Spalte.
- Passen Sie das Thema an die Host-Seite an. Dunkle Einbettungen sehen auf dunkleren Blogs und im Nachtmodus von Medium großartig aus. Hell funktioniert auf den meisten Marketing- und redaktionellen Websites.
- Sperren Sie CORS vor einer Sicherheitsprüfung. Der Standardwert
*akzeptiert Einbettungen von jedem Ursprung. Wenn dies für Ihr Programm wichtig ist, fügen Sie eine explizite Zulassungsliste hinzu, bevor Sie in Produktion gehen. - Der Snippet lebt für immer, sobald er eingefügt wurde. Wenn ein Botschafter den Snippet auf eine externe Website kopiert, ruft diese Website unbegrenzt Live-Daten von Ihrer REST-API ab. Wenn Sie jemals ein eingebettetes Element entfernen müssen, veröffentlichen Sie die Spendenaktion.
Entwicklerreferenz
Der Rest dieser Seite ist für Entwickler, die das Einbettungs-Widget anpassen.
Speicher für Einstellungen
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 '*'REST-Endpunkt
GET /wp-json/charitable-ambassadors/v1/embed-widget/<fundraiser_id>Gibt JSON zurück:
{
"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"
}Berechtigungen: öffentlich, keine Authentifizierung erforderlich, da das Widget auf externen Websites geladen werden muss. CORS wird durch den Filter charitable_ambassadors_embed_widget_cors_origins gesteuert, der standardmäßig die Einstellung für erlaubte CORS-Ursprünge liest.
Klassen
| Klasse | Datei | Rolle |
|---|---|---|
Charitable_Ambassadors_Embed_Widget_REST | includes/embed-widget/class-charitable-ambassadors-embed-widget-rest.php | Registrierung der REST-Route und CORS-Handler. |
Charitable_Ambassadors_Embed_Widget_Renderer | includes/embed-widget/class-charitable-ambassadors-embed-widget-renderer.php | Serverseitiges Rendern und das modale HTML. |
Filter
| Filter | Standard | Zweck |
|---|---|---|
charitable_ambassadors_embed_widget_enabled | Einstellungswert | Erzwingen Sie das Ein- oder Ausschalten der Funktion. |
charitable_ambassadors_embed_widget_cors_origins | Einstellungswert als Array | Die Liste der erlaubten Ursprünge für den REST-Endpunkt. Verwenden Sie [ '*' ] für alle. |
charitable_ambassadors_embed_widget_default_size | Einstellungswert | Überschreiben Sie die Standardgröße. |
charitable_ambassadors_embed_widget_default_theme | Einstellungswert | Überschreiben Sie das Standardthema. |
charitable_ambassadors_embed_widget_response | berechnet | Filtern Sie die REST-Antwortnutzlast. Empfängt ($payload, $fundraiser_id). |
charitable_ambassadors_embed_widget_docs_url | diese Seite | Überschreiben Sie die Dokumentations-URL, auf die der Link „How to embed“ verweist. |
Aktionen
| Aktion | Argumente | Wird ausgelöst, wenn |
|---|---|---|
charitable_ambassadors_embed_widget_rendered | $fundraiser_id, $size, $theme | Serverseitiges Rendern abgeschlossen. |
JS API
Das Widget-Skript stellt ein kleines globales Objekt bereit, das Sie von der JS-Seite der Host-Seite aufrufen können, um eine Datenaktualisierung außerhalb des normalen Abfrageintervalls zu erzwingen:
window.charitableEmbedWidget.refresh( containerEl );Funktionen
REST-Endpunkt: öffentliches Lesen. Admin-Einstellungen erfordern manage_charitable_settings.
Anpassungsbeispiele
CORS auf zwei vertrauenswürdige Ursprünge beschränken:
add_filter( 'charitable_ambassadors_embed_widget_cors_origins', function () {
return [ 'https://partner.example.com', 'https://blog.yoursite.com' ];
} );Dunkles Design immer erzwingen, unabhängig von der Wahl des Botschafters:
add_filter( 'charitable_ambassadors_embed_widget_default_theme', function () {
return 'dark';
} );Fügen Sie ein benutzerdefiniertes Feld zur REST-Antwort hinzu (z. B. die Biografie des Botschafters):
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 );Blenden Sie die Kachel „Embed Widget“ aus dem Freigabe-Popover für bestimmte Benutzerrollen aus:
add_filter( 'charitable_ambassadors_embed_widget_enabled', function ( $enabled ) {
if ( ! current_user_can( 'edit_posts' ) ) {
return false;
}
return $enabled;
} );Zusammenfassung
Das deckt das Embed Widget von der Einrichtung bis zur Anpassung ab. Sobald Sie es aktivieren, können Ihre Botschafter ihre Spendenaktionen überall im Web bewerben und das Spenden-Erlebnis aktuell halten, ohne dass Sie zusätzlichen Aufwand haben. Aktivieren Sie es, legen Sie Ihre CORS-Richtlinie fest und überlassen Sie den Rest Ihren Botschaftern.
Wenn Sie Fragen zur CORS-Konfiguration oder zu anderen Themen haben, hilft Ihnen unser Support-Team gerne weiter.
Das könnten Sie auch interessieren
Dies sind die Dokumente, die am engsten mit dem Embed Widget und den Funktionen, mit denen es zusammenarbeitet, verbunden sind.
- Sharing Networks – das Freigabe-Popover, in dem die Kachel „Embed Widget“ neben den Social-Media-Buttons angezeigt wird.
- QR-Codes – eine weitere Kachel im Freigabe-Popover, die den Botschaftern eine andere Möglichkeit bietet, ihre Spendenaktion zu teilen.
- Fundraiser Page – die Seite, auf die der Spenden-Button des Widgets verlinkt.
- Hooks & Filter in Ambassadors – die vollständige Entwicklerreferenz.
