Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Cuando Sarah comparte su enlace de invitación y Marcus se registra para recaudar fondos, quieres que Sarah reciba el crédito. La atribución es lo que hace que eso suceda automáticamente, sin que Sarah tenga que enviar un código a nadie, sin que Marcus tenga que recordar mencionarla y sin que usted tenga que mantener una hoja de cálculo de quién reclutó a quién.

Esta página explica cómo Embajadores Benéficos establece esa conexión, primero en lenguaje sencillo y luego con los detalles técnicos completos en la parte inferior para desarrolladores.

La versión corta

Cuando alguien hace clic en un enlace de invitación, se almacena un pequeño dato (una "cookie") en su navegador. Le dice a su sitio, en efecto: "esta persona vino de Sarah".

La cookie permanece allí de forma discreta hasta por 30 días. Si, durante ese período, procede a enviar una recaudación de fondos, ya sea que lo haga inmediatamente después de hacer clic en el enlace, o tres semanas después desde una página diferente de su sitio, el sistema lee la cookie, ve que vino de Sarah y le da crédito a Sarah por el recluta.

Esa es la idea general. El resto de esta página son solo los detalles.

El viaje, paso a paso

1. Sarah shares her link    >    2. Marcus clicks    >    3. Cookie stored
                                                                ↓
6. You approve, Sarah gets credit  ←  5. Marcus submits  ←  4. Marcus browses your site

1. Sarah comparte su enlace

Desde su página Mis campañas, Sarah copia su URL de invitación personal y la comparte como quiera: correo electrónico, mensaje de texto, redes sociales, en persona. Su URL se ve algo así:

https://yoursite.com/?charitable-invite=jA4HZIx2AhBnouMN

La parte ?charitable-invite=… al final es un token único que la identifica *a ella* específicamente (y, si usó un botón de Recluta por campaña, la causa específica para la que está reclutando).

2. Marcus hace clic

El navegador de Marcus busca esa URL. Antes de que WordPress muestre algo, el manejador de URL de Embajadores intercepta la solicitud, busca el token y confirma que pertenece a un invitador real y activo (Sarah).

3. Se almacena la cookie

El sistema deja una pequeña cookie en el navegador de Marcus:

Propiedad	Valor
Nombre	charitable_invite_token
Qué contiene	El token de Sarah (la misma cadena de la URL)
Cuánto dura	30 días
Dónde es visible	Solo en su sitio, no en otros sitios

Esa cookie es la miga de pan. Es cómo su sitio recordará que Marcus vino de Sarah, incluso si cierra la pestaña y regresa más tarde desde una página completamente diferente.

Después de dejar la cookie, el sistema redirige a Marcus a su página de destino de invitación, la página que configuró en Benéfico > Embajadores > Invitaciones > Página de destino. La barra de URL se actualiza para que el parámetro ?charitable-invite=… ya no sea visible (ya no es necesario, la cookie está ahí ahora).

4. Marcus navega por su sitio

Aquí es donde la atribución se vuelve poderosa. Marcus podría enviar su recaudación de fondos ahora mismo, o podría:

• Leer primero su página "Sobre nosotros"
• Ver la campaña de la causa en detalle
• Guardar el sitio en marcadores y volver mañana
• Olvidarse por una semana, luego de repente recordarlo y buscar su sitio nuevamente

Cualquiera de ellos todavía funciona, siempre que ocurra dentro de los 30 días y en el mismo navegador. La cookie espera.

5. Marcus envía su recaudación de fondos

Finalmente, Marcus hace clic en “Iniciar una recaudación de fondos” (o en cualquier botón que lleve a tu formulario de envío), lo completa y lo envía. En ese momento, WordPress guarda su nueva recaudación de fondos como un borrador, y el manejador de atribución de Embajadores se ejecuta:

1. Lee la cookie charitable_invite_token del navegador de Marcus.
2. Busca el token para encontrar al invitador (Sarah).
3. Sella la nueva recaudación de fondos con dos metadatos: “invitado por ID de usuario = Sarah” y “a través del token = T123”.
4. Incrementa el claim_count del token de Sarah en 1.

Ese sello es lo que potencia cada función de “recluta” en Embajadores de Charitable.

6. Tú apruebas, Sarah recibe el crédito

Cuando apruebas la recaudación de fondos de Marcus (transicionándola a publicada, o si estás en aprobación automática, se publica inmediatamente), suceden tres cosas debido a ese sello:

• La recaudación de fondos de Marcus aparece en la vista “Tus reclutas” de Sarah en su página Mis Campañas.
• El recluta de Marcus cuenta para el widget de Reclutamiento en tu panel de Control General.
• Sarah recibe un correo electrónico de felicitación (“¡La recaudación de fondos de tu recluta ha sido aprobada!”), si has habilitado la configuración de Correo electrónico al invitador al aprobar.

Último clic vs. Primer clic: ¿Qué sucede cuando alguien hace clic en varios enlaces?

Imagina que Marcus ha visitado tu sitio dos veces:

• Día 1: hace clic en el enlace de invitación de Sarah, lee tu sitio, no se registra.
• Día 15: ve el enlace de invitación de James en una publicación de Facebook, hace clic en él, se registra ese mismo día.

¿Quién recibe el crédito: Sarah o James?

La respuesta predeterminada es último clic: James recibe el crédito, porque su enlace es el que convirtió a Marcus de “navegando” a “recaudando fondos”. Este es el modelo estándar en los sistemas de referencia y la opción más común para los programas de persona a persona.

Pero algunas organizaciones prefieren la atribución de primer clic: Sarah recibe el crédito porque ella es quien *introdujo* a Marcus a tu causa. Aunque el impulso de James fue el que cerró la venta, Sarah hizo el trabajo más difícil de atraer a alguien desconocido a tu órbita.

Cambiar a primer clic es una sola línea de código (ver la referencia del desarrollador a continuación). La contrapartida es puramente filosófica: no hay una respuesta correcta.

Casos límite que vale la pena conocer

Algunas situaciones surgen regularmente. Esto es lo que hace el sistema en cada una:

Situación	Qué sucede
Sarah hace clic en su propio enlace e intenta registrarse	Protección contra auto-reclutamiento. La página de destino muestra una variante especial de “no puedes reclutarte a ti mismo”. Incluso si Sarah de alguna manera llega al formulario de envío, el paso de atribución la omite y registra el intento.
La cuenta de Sarah se elimina entre el clic y la aprobación	La recaudación de fondos de Marcus todavía tiene el meta-sello de recluta, por lo que el widget de Control General todavía lo cuenta como un recluta, pero el invitador muestra “(usuario eliminado)” y no se envía el correo electrónico de felicitación.
Sarah revoca su token mientras Marcus está en proceso de registro	La atribución se omite silenciosamente. La recaudación de fondos de Marcus se crea normalmente; simplemente aterriza sin crédito de reclutador.
La cookie de 30 días de Marcus caduca antes de que envíe la información	El envío no tiene atribución. Si Marcus hace clic en el enlace de Sarah de nuevo antes de enviar, la cookie se renueva y la atribución funciona.
Marcus hace clic en el enlace en su teléfono pero se registra en su portátil	La cookie es por dispositivo. Sin sincronización de navegador (p. ej., sincronización de Chrome), el envío desde el portátil no tendrá atribución.
Dos clics del mismo enlace, mismo navegador	El view_count del token aumenta en 1; la caducidad de la cookie se restablece a 30 días desde el último clic. Nada más cambia.
Un plugin de caché está sirviendo la página de destino desde la caché	El sistema emite cabeceras no-cache en el paso de redirección y le dice al framework de caché de Pro que omita la página de destino. Si tu plugin de caché todavía la almacena en caché, es posible que la cookie no se establezca; verás un aviso de autocomprobación en la pestaña de administración de Invitaciones.

Dónde aparece la atribución en tu panel de administración

Una vez que un recluta ha sido atribuido, lo verás en estos lugares:

• Visión general > Widget de reclutamiento – cuenta para Total / Aprobado / Pendiente / Rechazado, y para el gráfico de series temporales de reclutamiento.
• Visión general > Widget de Principales Reclutadores – tu tabla de clasificación de quién está trayendo más reclutas.
• Mis Campañas > Tus Reclutas (front-end, para el invitador) – Sarah ve a Marcus en su lista.
• Invitaciones > Exportación CSV de Principales Reclutadores – exporta la tabla de clasificación completa para el rango de fechas activo.
• Invitaciones > Exportación CSV de Actividad Reciente – registro cronológico de cada evento de reclutamiento.

Dónde buscar cuando algo parece ir mal

Si un recluta no aparece donde esperas, consulta Herramientas Benéficas > Registro. Cada evento de atribución escribe una entrada allí:

Código de registro	Lo que significa
invite_clicked	Se hizo clic en una URL de invitación válida. Confirma que el clic llegó a tu sitio.
invite_claimed	Un envío fue atribuido con éxito a un invitador.
self_recruit_skipped	Un invitador intentó reclutarse a sí mismo. Se omitió la atribución.
attribution_skipped_revoked_token	El token fue revocado entre el clic y el envío.
inviter_deleted_at_approval	Se omitió el correo electrónico de aprobación porque el usuario invitador ya no existe.

Filtra el registro por source: ambassadors_invites para ver solo las entradas relacionadas con invitaciones.

---

Referencia del desarrollador

El resto de esta página es para desarrolladores que personalizan el sistema de atribución.

La cookie

Name:      charitable_invite_token
Value:     The 16-character base62 token string
Lifetime:  30 days (filterable via charitable_ambassadors_invite_cookie_lifetime)
Path:      /
SameSite:  Lax
Secure:    true when is_ssl(), otherwise false
HttpOnly:  false (intentional - may be read by frontend analytics)

La cookie se establece directamente con setcookie() de WP, no a través de JS, por lo que está disponible en la siguiente solicitud.

El manejador de URL

Charitable_Ambassadors_Invites::handle_invite_url() está enganchado a init con prioridad 1. Hace lo siguiente:

1. Devuelve anticipadamente si $_GET['charitable-invite'] está vacío.
2. Devuelve anticipadamente si is_admin() (las solicitudes de administrador no activan la atribución).
3. Busca el token a través de Charitable_Ambassadors_Invites_Tokens::lookup_by_token().
4. Devuelve anticipadamente si el token falta, está revocado o pertenece a un usuario eliminado.
5. Establece la cookie a través de setcookie().
6. Llama a Charitable_Ambassadors_Invites_Tokens::increment_view( $token_id ).
7. Emite charitable_nocache_headers() (Pro 1.8.15.2+) o nocache_headers() (fallback del núcleo de WP).
8. Resuelve la página de destino a través de charitable_ambassadors_get_invites_setting( 'landing_page_id' ) y construye una URL de redirección con charitable-invite eliminado.
9. wp_safe_redirect( $landing_url, 302 ) + exit.

El código de estado 302 es deliberado para que las capas de caché no memoricen la redirección en sí, solo la página de destino, que es dinámica por charitable_is_dynamic_page.

El manejador de atribución

Charitable_Ambassadors_Invites::on_campaign_submission_save() está enganchado a la acción charitable_campaign_submission_save de Pro. Firma:

do_action( 'charitable_campaign_submission_save', $data, $campaign_id, $user_id, $form );

El manejador es adaptativo a la firma porque el sistema de verificación lo invoca con una forma heredada de 2 argumentos ($fundraiser_id, $user_id); en producción, siempre recibe la forma de 4 argumentos. El manejador:

1. Resuelve el valor de la cookie ($_COOKIE['charitable_invite_token']).
2. Devuelve anticipadamente si no hay cookie.
3. Busca el token; devuelve anticipadamente en caso de no encontrarlo o estado revocado.
4. Guardia de auto-reclutamiento: devuelve anticipadamente si $token_row->inviter_user_id === (int) $user_id, registra self_recruit_skipped.
5. Writes the two attribution meta keys:

   update_post_meta( $campaign_id, '_charitable_ambassadors_invited_by_user_id', (int) $token_row->inviter_user_id );
   update_post_meta( $campaign_id, '_charitable_ambassadors_invited_via_token_id', (int) $token_row->token_id );
   

6. Llama a Charitable_Ambassadors_Invites_Tokens::increment_claim( $token_id ).
7. Dispara do_action( 'charitable_ambassadors_invite_claimed', $token_row, $campaign_id, $inviter_user_id ).
8. Registra invite_claimed en Herramientas de Charitable > Registro.

Las dos claves de meta de publicación

Estas son la fuente de verdad para todo lo posterior:

Clave de metadatos	Tipo	Usado por
_charitable_ambassadors_invited_by_user_id	int (ID de usuario de WP)	Widget de reclutamiento, vista Tus reclutas, puerta de enlace de correo electrónico de invitado al aprobar.
_charitable_ambassadors_invited_via_token_id	int (PK de token_id)	Analíticas a nivel de token. Permite rastrear a un recluta hasta una URL específica con ámbito.

El plugin nunca elimina estos elementos; incluso si se elimina al invitado, los metadatos permanecen (verás "(usuario eliminado)" en Principales reclutadores). Para borrar la atribución de un recluta específico, elimina directamente las entradas de post_meta:

delete_post_meta( $campaign_id, '_charitable_ambassadors_invited_by_user_id' );
delete_post_meta( $campaign_id, '_charitable_ambassadors_invited_via_token_id' );

Cambiar el modo de atribución

Añade a functions.php de tu tema o a un plugin específico del sitio:

add_filter( 'charitable_ambassadors_invite_attribution_mode', function () {
    return 'first_click'; // default is 'last_click'
} );

En first_click, el manejador de URL actualiza la cookie en cada clic (por lo que los recuentos de vistas son precisos por invitado), pero solo establece el valor de la cookie si no hay ninguna cookie existente. Una vez que se establece una cookie, los clics posteriores actualizan su caducidad pero no su valor.

En last_click (predeterminado), cada clic establece un nuevo valor de cookie, reemplazando a cualquier invitado anterior.

Filtros

Filtro	Predeterminado	Propósito
charitable_ambassadors_invite_attribution_mode	'last_click'	Cambiar a 'first_click'.
charitable_ambassadors_invite_cookie_lifetime	30 * DAY_IN_SECONDS	Duración de la cookie en segundos.
charitable_ambassadors_invite_cookie_samesite	'Lax'	Atributo de cookie SameSite. Usa 'Strict' si tus URLs de invitación solo se hacen clic desde enlaces en tu propio dominio.
charitable_ambassadors_invite_self_recruit_allowed	false	Establece true para deshabilitar la protección contra auto-reclutamiento. No recomendado.

Acciones

Acción	Argumentos	Se dispara cuando
charitable_ambassadors_invite_url_resolved	$token_row, $request	Después de que el manejador de URL valide el token, antes de que se establezca la cookie. Úsalo para cortocircuitar (p. ej., prohibir tokens específicos).
charitable_ambassadors_invite_clicked	$token_row, $request	Después de que se haya establecido la cookie.
charitable_ambassadors_invite_claimed	$token_row, $fundraiser_id, $inviter_user_id	Atribución exitosa.
charitable_ambassadors_invite_self_recruit_skipped	$token_row, $fundraiser_id	La protección de autocontratación bloqueó la atribución.
charitable_ambassadors_invite_attribution_skipped	$token_row, $reason, $fundraiser_id	Captura para cualquier resultado de atribución no exitoso. $reason es uno de 'revoked_token', 'self_recruit', 'no_cookie', 'deleted_inviter'.

Registro

Cada evento de atribución se registra en Herramientas de Caridad > Registro a través de charitable_log():

charitable_log( $code, $context, [
    'type'    => 'addon',
    'source'  => 'ambassadors_invites',
    'level'   => 'info', // or 'warning' for skip cases
    'user_id' => get_current_user_id(),
] );

Códigos de registro (el argumento $code):

Código	Nivel	Cuándo
invite_clicked	info	El manejador de URL resolvió un token válido.
invite_claimed	info	Envío atribuido correctamente.
self_recruit_skipped	advertencia	Guardado de autoinscripción despedido.
attribution_skipped_revoked_token	advertencia	El token fue revocado entre el clic y el envío.
inviter_deleted_at_approval	advertencia	El correo electrónico de aprobación se omitió porque el usuario del invitador ya no existe.
vista_admin_pagina_de_destino_no_configurada	info	El administrador vio la pestaña Invitaciones mientras no había ninguna página de destino configurada.

Caché

La página de destino es dinámica (por usuario, por token). El controlador de URL emite encabezados sin caché en cada clic de invitación, y el filtro charitable_is_dynamic_page de Pro 1.8.15.2 está configurado para que los complementos de caché omitan la página de destino por completo:

add_filter( 'charitable_is_dynamic_page', function ( $is_dynamic, $post_id ) {
    if ( charitable_ambassadors_is_invite_landing_page( $post_id ) ) {
        return true;
    }
    return $is_dynamic;
}, 10, 2 );

Si tienes una versión Pro anterior a la 1.8.15.2 (sin el filtro charitable_is_dynamic_page), la llamada de respaldo nocache_headers() cubre el paso de redirección pero no ayudará si un complemento de caché almacena en caché la página de destino directamente. La autocomprobación de Invitaciones te advertirá sobre este estado.

La tabla de tokens

Consulta Cómo se almacenan los datos de invitación para ver el esquema completo. Las columnas más relevantes para la atribución:

Columna	Tipo	Propósito
token_id	BIGINT PK	El entero marcado en la recaudación de fondos del recluta como _charitable_ambassadors_invited_via_token_id.
token	VARCHAR(32)	La cadena que aparece en la URL y la cookie.
inviter_user_id	BIGINT	El ID de usuario de WP del invitador.
id_campaña	BIGINT NULL	Cuando NO es NULL, la propuesta del recluta se adjunta automáticamente a esta campaña principal.
estado	VARCHAR(20)	'active' o 'revoked'. Los tokens revocados omiten la atribución.
claim_count	INT	Incrementado en 1 por cada atribución exitosa.

Relacionado

• Invitaciones – el documento principal de la característica.
• Cómo se almacenan los datos de invitación – el ciclo de vida de la tabla personalizada.
• Hooks y filtros en Embajadores – la referencia completa de filtros y acciones.