Requiere: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

La función de Invitaciones utiliza una pequeña tabla de base de datos personalizada para almacenar los tokens únicos que potencian las URL de invitación de sus embajadores. Esta página explica dónde está esa tabla, cuándo se crea, qué contiene y qué sucede si alguna vez desaparece.

Si nunca ha pensado en la base de datos de su sitio, la versión corta es: es una tabla pequeña y bien administrada que el plugin maneja automáticamente. El resto de esta página es para cuando sucede algo inusual (una actualización salió mal, una copia de seguridad no se restauró correctamente, un administrador pregunta "¿qué datos almacena esta función?") y necesita conocer los detalles.

La versión corta

Pregunta	Respuesta
¿Qué se almacena?	Una fila por token de invitación. Cada fila tiene la cadena del token, el ID de usuario del que invita, un ID de campaña opcional, una fecha de creación, una fecha de revocación (si se revocó), un recuento de vistas y un recuento de reclamaciones.
¿Dónde se almacena?	En una tabla personalizada llamada <wp_prefix>charitable_ambassadors_invite_tokens (por ejemplo, wp_charitable_ambassadors_invite_tokens).
¿Cuándo se crea la tabla?	La primera vez que habilita las Invitaciones en la página de administración. Hasta entonces, la tabla no existe.
¿Se almacenan datos personales?	No, solo el ID de usuario de WordPress del que invita. Sin nombres, sin correos electrónicos, sin IPs.

Cuándo se crea la tabla

Hasta que habilite las Invitaciones, la tabla personalizada no existe; la función es completamente opcional. La primera vez que active Habilitar Invitaciones en Benéfico > Embajadores > Invitaciones, verá una ventana modal de confirmación única que explica lo que está a punto de suceder:

“Activar Invitaciones creará una nueva tabla de base de datos para almacenar los tokens de invitación. La tabla es pequeña y solo la utiliza la función de Invitaciones. ¿Continuar?”

Confirme, y la tabla se crea a través del ayudante estándar dbDelta() de WordPress (el mismo mecanismo que utiliza cada plugin para administrar tablas personalizadas de forma segura). El esquema se reconstruye de forma idempotente; si la tabla ya existe, dbDelta() solo emite las sentencias ALTER que realmente necesita.

También se escribe una fila en wp_options:

charitable_ambassadors_invites_schema_version = '1.0'

Así es como el plugin sabe en qué versión del esquema se encuentra su tabla, para que las futuras actualizaciones puedan migrar limpiamente.

Qué hay dentro de la tabla

La tabla tiene ocho columnas: sin PII, sin importes de donación, nada que el que invita no vea ya en su propia página Mis Campañas:

Columna	Lo que almacena
id	Clave primaria autoincremental.
token	La cadena única que aparece en la URL. 16 caracteres, alfanuméricos.
user_id	El ID de usuario de WordPress del que invita.
id_campaña	(Opcional) Un ID de campaña padre, cuando el token está limitado a una causa específica.
creado_en	Cuándo se generó por primera vez el token.
revocado_en	Cuándo se revocó el token (null si está activo).
numero_de_visualizaciones	Cuántas veces alguien ha hecho clic en la URL de este token.
claim_count	Cuántos reclutas se han registrado con éxito a través de este token.

Eso es todo. Sin correos electrónicos, sin IPs, sin huellas dactilares del navegador. Tanto el que invita como el destinatario están protegidos.

Cómo se utiliza la tabla

Tres cosas suceden en esta tabla durante el funcionamiento normal:

1. Creación de tokens: la primera vez que un embajador elegible visita Mis campañas con Invitaciones activado, se crea una fila de token para él (y una fila adicional por cada campaña principal que posea).
2. Resolución de clics: cuando alguien hace clic en una URL de invitación, el controlador de URL busca el token para encontrar al remitente.
3. Contadores: view_count se incrementa en cada clic; claim_count se incrementa cuando un recluta se atribuye con éxito.

Ese es todo el ciclo de vida. No hay procesamiento en segundo plano, ni trabajos programados, ni sincronización con servicios externos.

Los cuatro estados de autocomprobación

La pestaña de administración de Invitaciones tiene una barra de autocomprobación que detecta los raros momentos en que algo va mal:

Verá	Qué va mal	Qué hacer
Rojo: "Habilitado pero falta la tabla de la base de datos"	Una actualización de plugin, una limpieza manual de la base de datos o la restauración de una copia de seguridad eliminaron la tabla mientras la configuración permanecía activada.	Haga clic en Recrear tabla: el esquema se reconstruye en su lugar. No hay pérdida de datos para los clics nuevos; los tokens antiguos se han ido.
Amarillo: "Esquema obsoleto"	Una futura actualización introdujo un esquema más nuevo; su instalación aún no se ha migrado.	Haga clic en Ejecutar actualización. La migración es segura e idempotente.
Azul: "Deshabilitado pero existen datos"	Desactivó la función, pero la tabla todavía está allí con filas de tokens.	O Reactivar (los datos se reanudan su uso) o Eliminar permanentemente y quitar tabla (los datos se pierden para siempre).
Azul: "Compatibilidad de caché desactivada"	Un plugin de caché puede almacenar en caché su página de destino de invitación, lo que rompería la atribución.	Active Compatibilidad con caché en Benéfico > Configuración > Avanzado > Varios.

La autocomprobación se ejecuta en cada visita a la pestaña Invitaciones y en Herramientas benéficas > Información del sitio. Es así como se entera de los problemas de la tabla antes de que afecten a sus clientes.

Desactivar la función (Desactivación suave)

Si decide que Invitaciones no es adecuado para su programa, Desactive Invitaciones en la parte superior de la pestaña de administración:

• El interruptor se pone en la posición de apagado.
• El shortcode deja de renderizarse en la página de destino (o muestra la vista previa del administrador cuando un administrador la ve).
• La tarjeta de recluta deja de aparecer en Mis campañas.
• El controlador de URL deja de procesar clics de ?charitable-invite=....
• La tabla permanece. El historial de tokens se conserva para que pueda reactivarlo más tarde sin perderlo.

Esto es reversible: vuelve a habilitarlo en cualquier momento y los tokens existentes seguirán funcionando.

Eliminar permanentemente los datos (desinstalación completa)

Si quieres que los datos desaparezcan, por ejemplo, para cumplir con el RGPD o porque has decidido que no volverás a usar Invitaciones, usa Eliminar permanentemente y quitar tabla en la parte inferior de la pestaña Invitaciones:

El flujo destructivo tiene intencionadamente varios pasos:

1. Haz clic en Eliminar permanentemente y quitar tabla.
2. Un modal de confirmación te pide que escribas el nombre de la tabla (por ejemplo, wp_charitable_ambassadors_invite_tokens) para confirmar.
3. Enviar. La tabla se elimina, se elimina la opción _schema_version y la configuración invites_enabled se establece en desactivada.
4. La acción se registra en Herramientas de Charitable > Registro con el ID de usuario del moderador.

Esta es una puerta de un solo sentido. La próxima vez que habilites Invitaciones, se creará una tabla nueva con cero filas.

Qué sucede durante una exportación / copia de seguridad

La tabla es una tabla MySQL normal dentro de tu base de datos de WordPress. Cualquier herramienta que haga copias de seguridad de bases de datos de WordPress (UpdraftPlus, BackupBuddy, mysqldump, las copias de seguridad automáticas de tu host) la incluye automáticamente. Las restauraciones funcionan de la misma manera: recuperas la base de datos, la tabla viene con ella.

Qué sucede durante una exportación de datos personales

La herramienta de Exportación de Datos Personales de WordPress exporta los datos de la cuenta de usuario de WordPress. La tabla de Invitaciones almacena referencias de user_id, por lo que los tokens de invitación de un usuario se incluyen en su exportación de datos personales (cadenas de tokens + recuentos de visualización/reclamación). No hay PII más allá del ID de usuario en la tabla.

Consejos

• No edites la tabla manualmente. La interfaz de administración del plugin expone todo lo que necesites: revocar un token, regenerar un token, ver recuentos. La edición manual de filas rompe la integridad de claim_count.
• Si restauras una copia de seguridad que no incluye esta tabla, la autocomprobación la detectará en la próxima visita del administrador y ofrecerá Recrear Tabla.
• El esquema tiene control de versiones. Las futuras actualizaciones del plugin pueden agregar columnas; la actualización es segura e idempotente.
• No hay SQL en este documento por diseño. Los esquemas cambian; los documentos no deben llevarlos. Lee siempre la clase Charitable_Ambassadors_Invites_Schema del plugin para obtener la lista canónica de columnas.

---

Referencia del desarrollador

El resto de esta página es para desarrolladores y administradores de bases de datos.

Clase de esquema

Charitable_Ambassadors_Invites_Schema::table_name();        // string - prefixed name
Charitable_Ambassadors_Invites_Schema::exists();            // bool   - does the table exist
Charitable_Ambassadors_Invites_Schema::is_current();        // bool   - exists + columns match + version current
Charitable_Ambassadors_Invites_Schema::schema_version();    // string - stored version (empty if no record)
Charitable_Ambassadors_Invites_Schema::create();            // creates via dbDelta + stamps version
Charitable_Ambassadors_Invites_Schema::upgrade();           // idempotent migration to current schema
Charitable_Ambassadors_Invites_Schema::drop();              // drops table + deletes schema-version option

Todos los métodos son estáticos y seguros para llamar desde cualquier contexto (el archivo se carga incondicionalmente para que la autocomprobación y la Información del sitio puedan interrogar el estado incluso cuando Invitaciones está deshabilitado).

Claves de opción

charitable_ambassadors_invites_schema_version       # current installed schema version
charitable_settings > ambassadors > invites_enabled # feature master switch

Clase de tokens

Para trabajar con filas en la tabla mediante programación:

Charitable_Ambassadors_Invites_Tokens::get_or_create( $user_id, $campaign_id = 0 );
Charitable_Ambassadors_Invites_Tokens::lookup_by_token_string( $token_string );
Charitable_Ambassadors_Invites_Tokens::lookup_by_id( $token_id );
Charitable_Ambassadors_Invites_Tokens::increment_view( $token_id );
Charitable_Ambassadors_Invites_Tokens::increment_claim( $token_id );
Charitable_Ambassadors_Invites_Tokens::revoke( $token_id );
Charitable_Ambassadors_Invites_Tokens::build_invite_url( $token_string );

Filtros

Filtro	Predeterminado	Propósito
nombre_tabla_invitaciones_embajadores_caridad	tokens_invitaciones_embajadores_caridad_wp	Anula el nombre de la tabla (por ejemplo, tablas con ámbito multisitio). No se recomienda en producción.
charitable_ambassadors_invitations_storage_docs_url	esta página	Anula la URL de la documentación a la que enlazan los banners de autocomprobación.

Acciones

Acción	Argumentos	Se dispara cuando
creado_esquema_invitaciones_embajadores_caridad	$nombre_tabla	Schema::create() realmente creó (no solo actualizó) la tabla.
actualizado_esquema_invitaciones_embajadores_caridad	desde_version_$from_version, hasta_version_$to_version	Schema::create() ejecutó dbDelta y aplicó ALTERs.
eliminado_esquema_invitaciones_embajadores_caridad	$nombre_tabla	Schema::drop() eliminó la tabla.

Integración de Información del Sitio

Herramientas de Caridad » Información del Sitio tiene un bloque de Embajadores que muestra:

• Si la tabla existe.
• La versión actual del esquema.
• El recuento total de filas.
• Si el esquema está actualizado.

Ver Información del Sitio para el diseño completo.

Multisitio

Cada sub-sitio obtiene su propia tabla porque el nombre de la tabla se antepone con $wpdb->prefix. La activación en red no cambia esto; la función todavía se activa por sub-sitio.

Exportación de datos personales

La función de Invitaciones registra un exportador de datos personales con las Herramientas de Privacidad de WordPress. Cuando un usuario solicita la exportación de sus datos personales, el exportador recorre sus filas de tokens e incluye las cadenas de tokens, fechas, recuentos de visualizaciones y recuentos de reclamaciones en su exportación.

Capacidades

Todas las operaciones de administración (recrear, actualizar, eliminar) requieren manage_charitable_settings. La desinstalación destructiva requiere además escribir el nombre de la tabla para confirmar.

Ejemplos de personalización

Ocultar la opción de desinstalación destructiva de un rol de usuario específico:

add_filter( 'user_has_cap', function ( $allcaps, $caps, $args ) {
    if ( ! empty( $caps ) && in_array( 'manage_charitable_settings', $caps, true ) ) {
        $user = get_userdata( $args[1] );
        if ( $user && in_array( 'finance_admin', (array) $user->roles, true ) ) {
            unset( $allcaps['manage_charitable_settings'] );
        }
    }
    return $allcaps;
}, 10, 3 );

Enviar un webhook a su sistema de auditoría cuando se active la desinstalación destructiva:

add_action( 'charitable_ambassadors_invites_schema_dropped', function ( $table_name ) {
    wp_remote_post( 'https://audit.example.com/hook', [
        'body' => [
            'event'      => 'invites_table_dropped',
            'table_name' => $table_name,
            'user_id'    => get_current_user_id(),
            'site_url'   => site_url(),
            'timestamp'  => time(),
        ],
    ] );
} );

Reenviar los banners de autocomprobación a sus documentos internos:

add_filter( 'charitable_ambassadors_invitations_storage_docs_url', function () {
    return home_url( '/internal/charitable-invitations-runbook/' );
} );

Relacionado

• Invitaciones – el documento principal de la característica.
• Cómo Funciona la Atribución – el flujo de clic para acreditar.
• Información del Sitio – el bloque de diagnóstico que muestra el estado de la tabla.
• Hooks y filtros en Embajadores: referencia completa.

---