Requires: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+
Your ambassadors don’t fundraise in a vacuum. They write blog posts, share stories on partner sites, and build landing pages on platforms that have nothing to do with your WordPress install. The Embed Widget gives them a way to bring their fundraiser into all of those places.
The Embed Widget lets your ambassadors paste a small HTML snippet on any external site: a blog post, a landing page, a partner site, and a Medium article. It renders their fundraiser’s live progress bar and donate button with no iframe, no install, and no JavaScript framework required. The widget pulls live data from your site’s REST API and stays in sync as donations come in.
It turns “share this link” into “embed this widget,” which means your fundraiser shows up in the actual context where people are reading, instead of asking them to click off to a separate site.
When You’d Use It
The Embed Widget opens up a lot of doors for ambassadors who are actively promoting their fundraiser beyond your site. Here are the most common situations:
- Ambassador blog posts: your ambassador writes about their fundraiser on their personal blog. Drop the widget in the post, and readers can donate without leaving the page.
- Partner and media sites: a local news site covers your event. They embed the widget so readers can donate in-line while they’re reading the story.
- Landing pages on other platforms: your marketing team builds a landing page on Webflow, Framer, or Squarespace. Paste the snippet, and you get a live widget with no plugin required.
- Internal dashboards: leadership wants a real-time view of the gala fundraiser on the company intranet. Embed it, and it updates automatically.
How to Get There
Go to Charitable » Ambassadors » Misc » Embed Widget. The widget is off by default.
Turn on Enable Embed Widget, configure the defaults, and the Embed Widget tile will appear in the share popover on every fundraiser page.
The Settings
| Setting | Default | Effect |
|---|---|---|
| Enable Embed Widget | Off | Master switch. Until it’s on, the Embed Widget tile is hidden from every share popover. |
| Default Snippet Size | Compact (320×500) | Which size the modal offers first. Compact works well in sidebars and narrow columns. Wide (600×320) suits full-width hero blocks. |
| Default Snippet Theme | Light | Light or Dark. Ambassadors can override this per-embed inside the modal. |
| CORS Allowed Origins | * (all origins) | One origin per line, or * to allow any. The REST endpoint enforces this header. |
The defaults are what the snippet builder starts with. Ambassadors can flip the size or theme inside the modal before copying, so these are starting points rather than hard limits.
The User Flow
From any fundraiser page, a visitor or the ambassador themselves clicks the Share button and picks Embed Widget. The modal that opens has three sections:
- Live preview: a real-time render of what the widget will look like at the chosen size and theme.
- Size and theme toggles: flip between Compact and Wide, or Light and Dark.
- Snippet: a copyable textarea with the exact HTML. One Copy Snippet button and it’s ready to paste.
The snippet looks something like this:
<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>Paste that anywhere that allows <script> tags: a WordPress post, a Medium article, a Webflow embed block. The widget renders at page load and polls for updates automatically.
What Renders on the Destination Site
The widget shows everything a visitor needs to understand and support the fundraiser, without leaving the page they’re on:
- Featured image (small thumbnail at the top in Compact, left-aligned hero in Wide).
- Title and ambassador name.
- Current raised amount and goal with a progress bar.
- Donor count.
- A Donate button that opens the fundraiser page in a new tab, so the actual donation flow uses your live form rather than a mini form inside the widget.
Live updates happen every 30 seconds via the REST endpoint, so the numbers stay accurate as donations come in.
CORS Configuration
Because the widget loads on third-party sites, the REST endpoint needs CORS headers. The default * allows any origin, which is convenient for getting started. If your security policy requires an explicit allowlist, replace * with one origin per line:
https://partner.example.com
https://blog.yoursite.com
https://medium.comThe endpoint emits an Access-Control-Allow-Origin header matching the request’s Origin when it finds a match in the list.
When the Widget Can’t Render
Three situations can prevent the widget from displaying. In each case the fallback is designed so the host page is never broken by a bad embed.
| State | What renders |
|---|---|
| Fundraiser doesn’t exist | A “Fundraiser unavailable” placeholder. The browser console logs an error with the fundraiser ID. |
| Fundraiser is unpublished | “Fundraiser unavailable” – same as above. The public visibility check matches the public fundraiser page. |
| CORS denied | The widget container stays empty. The browser console shows the CORS error. The host page itself is unaffected. |
Tips Worth Keeping in Mind
A few things that make the Embed Widget work better in practice.
- Use Wide for hero sections, Compact for sidebars. Wide is 600×320 and works well in a featured-content slot. Compact is 320×500 and fits naturally in a vertical sidebar or narrow column.
- Match the theme to the host site. Dark embeds look great on darker blogs and Medium’s night mode. Light works on most marketing and editorial sites.
- Lock down CORS before a security audit. The default
*accepts embeds from any origin. If that matters to your program, add an explicit allowlist before you go to production. - The snippet lives forever once it’s pasted. When an ambassador copies the snippet onto an external site, that site keeps fetching live data from your REST API indefinitely. If you ever need to retire an embed, unpublish the fundraiser.
Developer Reference
The rest of this page is for developers customizing the embed widget.
Settings Storage
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 Endpoint
GET /wp-json/charitable-ambassadors/v1/embed-widget/<fundraiser_id>Returns 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"
}Capabilities: public, no auth required, since the widget needs to load on external sites. CORS is controlled by the charitable_ambassadors_embed_widget_cors_origins filter, which defaults to reading the CORS Allowed Origins setting.
Classes
| Class | File | Role |
|---|---|---|
Charitable_Ambassadors_Embed_Widget_Rest | includes/embed-widget/class-charitable-ambassadors-embed-widget-rest.php | REST route registration and CORS handler. |
Charitable_Ambassadors_Embed_Widget_Renderer | includes/embed-widget/class-charitable-ambassadors-embed-widget-renderer.php | Server-side render and the modal HTML. |
Filters
| Filter | Default | Purpose |
|---|---|---|
charitable_ambassadors_embed_widget_enabled | setting value | Force the feature on or off. |
charitable_ambassadors_embed_widget_cors_origins | setting value as array | The list of allowed origins for the REST endpoint. Use [ '*' ] for any. |
charitable_ambassadors_embed_widget_default_size | setting value | Override the default size. |
charitable_ambassadors_embed_widget_default_theme | setting value | Override the default theme. |
charitable_ambassadors_embed_widget_response | computed | Filter the REST response payload. Receives ($payload, $fundraiser_id). |
charitable_ambassadors_embed_widget_docs_url | this page | Override the docs URL the “How to embed” link points at. |
Actions
| Action | Args | Fires when |
|---|---|---|
charitable_ambassadors_embed_widget_rendered | $fundraiser_id, $size, $theme | Server-side render completes. |
JS API
The widget script exposes a small global you can call from the host page’s JS to force a data refresh outside the normal polling interval:
window.charitableEmbedWidget.refresh( containerEl );Capabilities
REST endpoint: public read. Admin settings require manage_charitable_settings.
Customization Examples
Restrict CORS to two trusted origins:
add_filter( 'charitable_ambassadors_embed_widget_cors_origins', function () {
return [ 'https://partner.example.com', 'https://blog.yoursite.com' ];
} );Always force the Dark theme regardless of the ambassador’s choice:
add_filter( 'charitable_ambassadors_embed_widget_default_theme', function () {
return 'dark';
} );Add a custom field to the REST response (for example, the ambassador’s bio):
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 );Hide the Embed Widget tile from the share popover for specific user roles:
add_filter( 'charitable_ambassadors_embed_widget_enabled', function ( $enabled ) {
if ( ! current_user_can( 'edit_posts' ) ) {
return false;
}
return $enabled;
} );Wrapping Up
That covers the Embed Widget from setup to customization. Once you turn it on, your ambassadors can promote their fundraisers anywhere on the web and keep the donation experience live and current without any extra work on your end. Enable it, set your CORS policy, and let your ambassadors do the rest.
If you run into questions about CORS configuration or anything else, our support team is happy to help.
You May Also Want to Read
These are the docs most closely connected to the Embed Widget and the features it works alongside.
- Sharing Networks – the share popover where the Embed Widget tile lives alongside the social network buttons.
- QR Codes – another share popover tile that gives ambassadors a different way to share their fundraiser.
- Fundraiser Page – the page the Donate button on the widget links back to.
- Hooks & filters in Ambassadors – the full developer reference.
