Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+
Tus embajadores no recaudan fondos en el vacío. Escriben publicaciones de blog, comparten historias en sitios asociados y crean páginas de destino en plataformas que no tienen nada que ver con tu instalación de WordPress. El Widget de Incrustación les da una forma de llevar su recaudación de fondos a todos esos lugares.
El Widget de Incrustación permite a tus embajadores pegar un pequeño fragmento de HTML en cualquier sitio externo: una publicación de blog, una página de destino, un sitio asociado y un artículo de Medium. Muestra la barra de progreso en vivo de su recaudación y el botón para donar sin necesidad de iframe, instalación o framework de JavaScript. El widget extrae datos en vivo de la API REST de tu sitio y se mantiene sincronizado a medida que llegan las donaciones.
Convierte "comparte este enlace" en "incrusta este widget", lo que significa que tu recaudación de fondos aparece en el contexto real donde la gente está leyendo, en lugar de pedirles que hagan clic en un sitio separado.
Cuándo usarlo
El Widget de Incrustación abre muchas puertas para los embajadores que promocionan activamente su recaudación de fondos más allá de tu sitio. Aquí están las situaciones más comunes:
- Publicaciones de blog de embajadores: tu embajador escribe sobre su recaudación de fondos en su blog personal. Inserta el widget en la publicación y los lectores podrán donar sin salir de la página.
- Sitios de socios y medios: un sitio de noticias local cubre tu evento. Incrustan el widget para que los lectores puedan donar en línea mientras leen la noticia.
- Páginas de destino en otras plataformas: tu equipo de marketing crea una página de destino en Webflow, Framer o Squarespace. Pega el fragmento y obtendrás un widget en vivo sin necesidad de plugin.
- Paneles internos: la dirección quiere una vista en tiempo real de la recaudación de fondos de la gala en la intranet de la empresa. Incrusta el widget y se actualizará automáticamente.
Cómo llegar
Ve a Benéfica » Embajadores » Varios » Widget de Incrustación. El widget está desactivado por defecto.
Activa Habilitar Widget de Incrustación, configura los valores predeterminados y la ficha del Widget de Incrustación aparecerá en la ventana emergente de compartir de cada página de recaudación de fondos.
La Configuración
| Configuración | Predeterminado | Efecto |
|---|---|---|
| Habilitar Widget de Incrustación | Desactivado | Interruptor principal. Hasta que esté activado, la ficha del Widget de Incrustación estará oculta en todas las ventanas emergentes de compartir. |
| Tamaño Predeterminado del Fragmento | Compacto (320×500) | Qué tamaño ofrece primero la ventana modal. Compacto funciona bien en barras laterales y columnas estrechas. Ancho (600×320) se adapta a bloques de héroe de ancho completo. |
| Tema Predeterminado del Fragmento | Claro | Claro u Oscuro. Los embajadores pueden anular esto por incrustación dentro de la ventana modal. |
| Orígenes Permitidos CORS | `*` (todos los orígenes) | Un origen por línea, o `*` para permitir cualquiera. El endpoint REST aplica esta cabecera. |
Los valores predeterminados son con los que comienza el generador de fragmentos. Los embajadores pueden cambiar el tamaño o el tema dentro de la ventana modal antes de copiar, por lo que estos son puntos de partida en lugar de límites estrictos.
El Flujo de Usuario
Desde cualquier página de recaudación de fondos, un visitante o el propio embajador hace clic en el botón Compartir y selecciona Incrustar widget. El modal que se abre tiene tres secciones:
- Vista previa en vivo: una representación en tiempo real de cómo se verá el widget con el tamaño y el tema elegidos.
- Interruptores de tamaño y tema: alterna entre Compacto y Ancho, o Claro y Oscuro.
- Fragmento: un área de texto copiable con el HTML exacto. Un botón Copiar fragmento y está listo para pegar.
El fragmento se parece a esto:
<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>Pega eso en cualquier lugar que permita etiquetas <script>: una publicación de WordPress, un artículo de Medium, un bloque de inserción de Webflow. El widget se renderiza al cargar la página y sondea las actualizaciones automáticamente.
Lo que se renderiza en el sitio de destino
El widget muestra todo lo que un visitante necesita para comprender y apoyar la recaudación de fondos, sin salir de la página en la que se encuentra:
- Imagen destacada (pequeña miniatura en la parte superior en Compacto, imagen principal alineada a la izquierda en Ancho).
- Título y nombre del embajador.
- Cantidad recaudada actual y objetivo con una barra de progreso.
- Número de donantes.
- Un botón Donar que abre la página de recaudación de fondos en una nueva pestaña, de modo que el flujo de donación real utilice tu formulario en vivo en lugar de un mini formulario dentro del widget.
Las actualizaciones en vivo ocurren cada 30 segundos a través del punto final REST, por lo que los números se mantienen precisos a medida que llegan las donaciones.
Configuración de CORS
Dado que el widget se carga en sitios de terceros, el punto final REST necesita encabezados CORS. El valor predeterminado * permite cualquier origen, lo que es conveniente para empezar. Si tu política de seguridad requiere una lista de permitidos explícita, reemplaza * con un origen por línea:
https://partner.example.com
https://blog.yoursite.com
https://medium.comEl punto final emite un encabezado Access-Control-Allow-Origin que coincide con el Origen de la solicitud cuando encuentra una coincidencia en la lista.
Cuándo el widget no se puede renderizar
Tres situaciones pueden impedir que el widget se muestre. En cada caso, el sistema de reserva está diseñado para que la página anfitriona nunca se rompa por una inserción incorrecta.
| Estado | Qué se representa |
|---|---|
| La recaudación de fondos no existe | Un marcador de posición "Recaudación de fondos no disponible". La consola del navegador registra un error con el ID de la recaudación de fondos. |
| La recaudación de fondos no está publicada | "Recaudación de fondos no disponible" - igual que lo anterior. La comprobación de visibilidad pública coincide con la página pública de recaudación de fondos. |
| CORS denegado | El contenedor del widget permanece vacío. La consola del navegador muestra el error CORS. La página anfitriona en sí no se ve afectada. |
Consejos que vale la pena tener en cuenta
Algunas cosas que hacen que el widget incrustado funcione mejor en la práctica.
- Usa Ancho para secciones principales, Compacto para barras laterales. Ancho es 600x320 y funciona bien en una ranura de contenido destacado. Compacto es 320x500 y encaja de forma natural en una barra lateral vertical o una columna estrecha.
- Adapta el tema al sitio anfitrión. Los widgets oscuros quedan geniales en blogs más oscuros y en el modo nocturno de Medium. El claro funciona en la mayoría de los sitios de marketing y editoriales.
- Bloquea CORS antes de una auditoría de seguridad. El valor predeterminado
*acepta incrustaciones de cualquier origen. Si eso es importante para tu programa, agrega una lista de permitidos explícita antes de pasar a producción. - El fragmento vive para siempre una vez que se pega. Cuando un embajador copia el fragmento en un sitio externo, ese sitio sigue obteniendo datos en vivo de tu API REST indefinidamente. Si alguna vez necesitas retirar una incrustación, despublica la recaudación de fondos.
Referencia del desarrollador
El resto de esta página es para desarrolladores que personalizan el widget de incrustación.
Almacenamiento de configuración
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 '*'Endpoint REST
GET /wp-json/charitable-ambassadors/v1/embed-widget/<fundraiser_id>Devuelve 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"
}Capacidades: público, sin autenticación requerida, ya que el widget necesita cargarse en sitios externos. CORS está controlado por el filtro charitable_ambassadors_embed_widget_cors_origins, que por defecto lee la configuración de Orígenes permitidos de CORS.
Clases
| Clase | Archivo | Rol |
|---|---|---|
Charitable_Ambassadors_Embed_Widget_REST | includes/embed-widget/class-charitable-ambassadors-embed-widget-rest.php | Registro de rutas REST y manejador CORS. |
Charitable_Ambassadors_Embed_Widget_Renderer | includes/embed-widget/class-charitable-ambassadors-embed-widget-renderer.php | Renderizado del lado del servidor y el HTML del modal. |
Filtros
| Filtro | Predeterminado | Propósito |
|---|---|---|
charitable_ambassadors_embed_widget_enabled | valor de configuración | Forzar la activación o desactivación de la función. |
charitable_ambassadors_embed_widget_cors_origins | valor de configuración como array | La lista de orígenes permitidos para el punto final REST. Usa [ '*' ] para cualquiera. |
charitable_ambassadors_embed_widget_default_size | valor de configuración | Anular el tamaño predeterminado. |
charitable_ambassadors_embed_widget_default_theme | valor de configuración | Anular el tema predeterminado. |
charitable_ambassadors_embed_widget_response | calculado | Filtrar el payload de la respuesta REST. Recibe ($payload, $fundraiser_id). |
charitable_ambassadors_embed_widget_docs_url | esta página | Anular la URL de la documentación a la que apunta el enlace "Cómo incrustar". |
Acciones
| Acción | Argumentos | Se dispara cuando |
|---|---|---|
charitable_ambassadors_embed_widget_rendered | $fundraiser_id, $size, $theme | El renderizado del lado del servidor se completa. |
API JS
El script del widget expone una pequeña variable global que puedes llamar desde el JS de la página anfitriona para forzar una actualización de datos fuera del intervalo de sondeo normal:
window.charitableEmbedWidget.refresh( containerEl );Capacidades
Punto final REST: lectura pública. La configuración de administrador requiere manage_charitable_settings.
Ejemplos de personalización
Restringir CORS a dos orígenes de confianza:
add_filter( 'charitable_ambassadors_embed_widget_cors_origins', function () {
return [ 'https://partner.example.com', 'https://blog.yoursite.com' ];
} );Forzar siempre el tema oscuro independientemente de la elección del embajador:
add_filter( 'charitable_ambassadors_embed_widget_default_theme', function () {
return 'dark';
} );Añadir un campo personalizado a la respuesta REST (por ejemplo, la biografía del embajador):
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 );Ocultar el icono del Widget de Incrustación del menú emergente de compartir para roles de usuario específicos:
add_filter( 'charitable_ambassadors_embed_widget_enabled', function ( $enabled ) {
if ( ! current_user_can( 'edit_posts' ) ) {
return false;
}
return $enabled;
} );Conclusión
Eso cubre el Widget de Incrustación desde la configuración hasta la personalización. Una vez que lo actives, tus embajadores podrán promocionar sus recaudaciones de fondos en cualquier lugar de la web y mantener la experiencia de donación actualizada y al día sin ningún trabajo adicional por tu parte. Actívalo, establece tu política CORS y deja que tus embajadores hagan el resto.
Si tienes preguntas sobre la configuración de CORS o cualquier otra cosa, nuestro equipo de soporte estará encantado de ayudarte.
También te Puede Interesar Leer
Estos son los documentos más estrechamente relacionados con el Widget de Incrustación y las funciones con las que funciona.
- Redes para Compartir: el menú emergente para compartir donde el icono del Widget de Incrustación convive con los botones de redes sociales.
- Códigos QR: otro icono del menú emergente para compartir que ofrece a los embajadores una forma diferente de compartir su recaudación de fondos.
- Página de Recaudación de Fondos: la página a la que enlaza el botón Donar del widget.
- Hooks y filtros en Embajadores – la referencia completa para desarrolladores.
