La función de Enlace Mágico permite a los donantes acceder a su panel de donante sin necesidad de una cuenta de usuario de WordPress ni de iniciar sesión. Los donantes pueden solicitar un enlace seguro y de tiempo limitado por correo electrónico que les otorga acceso para ver su historial de donaciones e información de cuenta.
Tabla de Contenidos
Ganchos y filtros
Los siguientes hooks y filtros de PHP están disponibles para extender y personalizar la funcionalidad del enlace mágico:
Filtros de Enlace Mágico
charitable_magic_link_logout_redirect– Filtra la URL de redirección después del cierre de sesión del enlace mágico- Parámetros:
$redirect_url(string) - Devuelve: Cadena de URL de redirección modificada
- Nota: El resultado del filtro se valida para evitar redirigir de nuevo al panel del donante
- Parámetros:
charitable_is_magic_link_on_page– Determina si la funcionalidad del enlace mágico debe estar activa en la página actual- Parámetros:
$is_magic_link_on_page(bool) - Devuelve: Booleano
- Por defecto: Verdadero si está en la página del panel del donante, tiene la acción donor_dashboard, o tiene magic_link_token
- Parámetros:
charitable_magic_link_verify_throttle– Filtra el período de limitación para las solicitudes de clave de verificación (en segundos)- Parámetros: Ninguno
- Devuelve: Entero (por defecto: 300 segundos / 5 minutos)
charitable_magic_link_limit_throttle– Filtra el número máximo de solicitudes de enlace mágico permitidas por período de limitación- Parámetros: Ninguno
- Devuelve: Entero (por defecto: 3 solicitudes)
charitable_magic_link_token_expiration– Filtra el tiempo de expiración del token (en segundos)- Parámetros: Ninguno
- Devuelve: Entero (por defecto: 7200 segundos / 2 horas)
charitable_magic_link_token_expired_message– Filtra el mensaje de error que se muestra cuando el token expira- Parámetros:
$message(string) - Devuelve: Cadena de mensaje modificada
- Parámetros:
Filtros de Correo Electrónico
charitable_email_magic_link_name– Filtra el nombre/título del correo electrónico- Parámetros:
$name(string) - Devuelve: Cadena de nombre de correo electrónico modificado
- Parámetros:
charitable_email_magic_link_default_subject– Filtra la línea de asunto del correo electrónico predeterminada- Parámetros:
$subject(string),$email(instancia de Charitable_Email_Magic_Link) - Devuelve: Cadena de asunto modificado
- Parámetros:
charitable_email_magic_link_default_headline– Filtra el titular predeterminado del correo electrónico- Parámetros:
$headline(string),$email(instancia de Charitable_Email_Magic_Link) - Devuelve: Cadena de titular modificado
- Parámetros:
charitable_email_magic_link_default_body– Filtra el contenido del cuerpo del correo electrónico predeterminado- Parámetros:
$body(string),$email(instancia de Charitable_Email_Magic_Link) - Devuelve: Cadena de cuerpo modificado
- Parámetros:
Filtros de plantilla del panel
charitable_magic_link_dashboard_access_heading– Filtra el texto del encabezado para el formulario de acceso al enlace mágico- Parámetros:
$heading(string) - Devuelve: Encabezado modificado
- Parámetros:
charitable_magic_link_dashboard_access_description– Filtra el texto de la descripción para el formulario de acceso al enlace mágico- Parámetros:
$description(string) - Devuelve: Descripción modificada
- Parámetros:
charitable_magic_link_form_shortcode– Filtra la salida del shortcode del formulario de enlace mágico- Parámetros:
$output(string) - Devuelve: Salida del shortcode modificado
- Parámetros:
Flujo de autenticación
- Usuarios registrados: Si un usuario de WordPress ha iniciado sesión, se omite el enlace mágico y se utiliza la autenticación de usuario estándar
- Usuarios de enlace mágico: Si no ha iniciado sesión, el sistema comprueba si el token del enlace mágico es válido
- Sin autenticación: Si no existe ninguno de los dos, se muestra el formulario de enlace mágico (si está habilitado)
Ajustes y Configuración
La funcionalidad del enlace mágico se puede configurar en Charitable → Ajustes → Donantes → Enlace mágico.
Configuración
- Habilitar enlace mágico – Activar/desactivar la funcionalidad del enlace mágico
- Predeterminado: Habilitado
- Nota: Requiere que el panel del donante esté habilitado y que la actualización de la base de datos se haya completado
- Expiración del enlace mágico (horas) – Cuánto tiempo permanecen válidos los enlaces mágicos
- Por defecto: 2 horas
- Rango: Configurable a través del filtro
charitable_magic_link_token_expiration - Nota: La expiración se calcula desde la creación del token (no desde el envío del correo electrónico)
Requisitos
- El panel del donante debe estar habilitado
- La actualización de la base de datos para las columnas de enlace mágico debe estar completada
- El correo electrónico del enlace mágico no se puede deshabilitar mientras el enlace mágico esté habilitado
Funciones de Seguridad
El sistema de enlace mágico incluye varias medidas de seguridad:
Limitación de velocidad
- Límite de Solicitudes: Máximo 3 solicitudes de enlace mágico por ventana de 5 minutos por donante
- Ventana de Límite: 5 minutos (configurable a través de
charitable_magic_link_verify_throttle) - Límite de Solicitudes: 3 solicitudes (configurable a través de
charitable_magic_link_limit_throttle) - Implementación: Utiliza la caché de objetos de WordPress y los metadatos del donante para rastrear los recuentos de solicitudes
Seguridad del Token
- Tokens Únicos: Solo un token activo por donante a la vez
- Invalidación de Token: Cuando se solicita un nuevo enlace mágico, todos los tokens existentes para ese donante se invalidan
- Expiración: Los tokens expiran automáticamente después del período de tiempo configurado
- Cookies Seguras: Los tokens almacenados en cookies utilizan las marcas HttpOnly y Secure (cuando SSL está disponible)
Validación de Sesión
- Coincidencia de ID de Donante: El ID de donante de la sesión debe coincidir con el ID de donante del token
- Validación de Solicitud: Las solicitudes AJAX validan que el ID de donante del token coincida con el ID de donante solicitado
- Protección contra Desajuste de Sesión: Si los ID de donante de la sesión y del token no coinciden, la sesión se borra y se requiere una reautenticación
Seguridad de Cierre de Sesión
- Protección de Nonce: El cierre de sesión requiere un nonce válido para prevenir ataques CSRF
- Invalidación de Token: El cierre de sesión invalida todos los tokens del donante en la base de datos
- Borrado de Cookies: Todas las cookies de enlace mágico se borran al cerrar sesión
- Borrado de Sesión: Todos los datos de sesión de enlace mágico se borran
Estructura de la Base de Datos
La funcionalidad de enlace mágico utiliza las siguientes columnas de base de datos en la tabla wp_charitable_donors:
Columnas
magic_link_token– Almacena el token de acceso persistente (cadena de 32 caracteres)- Establecido cuando se usa la clave de verificación por primera vez
- Borrado cuando el token expira o se invalida
- Utilizado para la autenticación continua
magic_link_verify_key– Almacena la clave de verificación inicial (cadena de 32 caracteres)- Establecido cuando se envía el correo electrónico del enlace mágico
- Convertido a token en el primer uso
- Borrado después de la conversión o expiración
magic_link_verify_throttle– Almacena la marca de tiempo para la limitación de velocidad y la expiración del token- Se utiliza para rastrear cuándo se creó la clave de verificación (para limitación de velocidad)
- Se utiliza para rastrear cuándo se creó el token (para la comprobación de expiración)
- Formato: fecha y hora de MySQL (Y-m-d H:i:s)
Meta del donante
_charitable_magic_link_throttle_count– Rastrea el número de solicitudes de enlace mágico en la ventana de limitación actual- Incrementado en cada solicitud
- Restablecido cuando expira la ventana de limitación
- Se utiliza con la caché de objetos para aplicar la limitación de velocidad
Sistema de Correo Electrónico
El correo electrónico del enlace mágico es un tipo de correo electrónico requerido que no se puede deshabilitar mientras el enlace mágico esté habilitado.
Clase de correo electrónico
- Clase:
Charitable_Email_Magic_Link - ID de correo electrónico:
magic_link - Requerido: Sí (no se puede deshabilitar mientras el enlace mágico esté habilitado)
Campos de correo electrónico
El correo electrónico del enlace mágico incluye los siguientes campos personalizados:
{magic_link}– La URL segura para acceder al panel del donante- Contiene la clave de verificación como parámetro
magic_link_token - Apunta a la URL de la página del panel del donante
- Contiene la clave de verificación como parámetro
{donor_name}– El nombre del donante (o "Estimado donante" si no está disponible){expiration_time}– Hora de expiración legible por humanos (por ejemplo, "dentro de 2 horas")
Etiquetas de plantilla de correo electrónico
Las etiquetas de plantilla de correo electrónico estándar de Charitable están disponibles, además de los campos personalizados enumerados anteriormente.
Filtros de Correo Electrónico
Se aplican todos los filtros de correo electrónico estándar de Charitable, además de los filtros específicos de enlace mágico enumerados en la sección Hooks y Filtros.
Shortcode
El formulario de enlace mágico se puede mostrar usando un shortcode.
Shortcode
- Código corto:
[charitable_magic_link_form] - Atributos: Ninguno compatible actualmente
- Salida: Muestra el formulario de solicitud de enlace mágico
Proceso del formulario
- El usuario introduce la dirección de correo electrónico
- El formulario valida el formato del correo electrónico
- El sistema comprueba si existe un donante con ese correo electrónico
- Se comprueba la limitación de velocidad
- Si se permite, se envía el correo electrónico de enlace mágico
- Se muestra un mensaje de éxito o error
Validación del formulario
- Correo electrónico requerido: Debe ser una dirección de correo electrónico válida
- El donante debe existir: El correo electrónico debe estar asociado a al menos una donación
- Limitación de velocidad: No debe exceder los límites de solicitud
Funciones Auxiliares
Las siguientes funciones de ayuda están disponibles para los desarrolladores:
Comprobar funciones
charitable_is_magic_link_enabled()– Comprueba si el enlace mágico está habilitado- Devuelve:
bool - Comprobaciones: Panel del donante habilitado, actualización de la base de datos completada, configuración habilitada
- Devuelve:
charitable_is_authenticated_via_magic_link()– Comprueba si el usuario actual está autenticado a través de un enlace mágico- Devuelve:
bool - Comprueba la validez de la sesión y del token
- Devuelve:
charitable_get_donor_id_from_magic_link()– Obtiene el ID del donante de la autenticación del enlace mágico- Devuelve:
int|false - Devuelve el ID del donante si existe un token de enlace mágico válido, de lo contrario, devuelve false
- Devuelve:
Métodos de clase
La clase Charitable_Magic_Link proporciona los siguientes métodos públicos:
get_instance()– Obtiene la instancia singleton de la claseget_token()– Obtiene el token de la cookie o del parámetro GETis_valid_token($token)– Comprueba si un token es válido y no ha expiradois_valid_verify_key($token)– Comprueba si una clave de verificación es válidaget_donor_by_token($token)– Obtiene el objeto donante por tokenget_donor_by_verify_key($verify_key)– Obtiene el objeto donante por clave de verificacióncan_send_email($donor_id)– Comprueba si se puede enviar el correo electrónico del enlace mágico (limitación de velocidad)send_email($donor_id, $email)– Envía el correo electrónico del enlace mágico al donantegenerate_verify_key()– Genera una nueva clave de verificación (cadena aleatoria de 32 caracteres)
Ciclo de Vida del Token
Creación de token
- El usuario solicita un enlace mágico:
- El donante introduce el correo electrónico en el formulario
- El sistema genera una clave de verificación
- La clave de verificación se almacena en
magic_link_verify_key - Se envía un correo electrónico con la clave de verificación en la URL
- El usuario hace clic en el enlace del correo electrónico:
- La clave de verificación se valida
- La clave de verificación se convierte en token
- El token se almacena en
magic_link_token - La clave de verificación se elimina de la base de datos
- Se establece una cookie con el token
- Se crea la sesión
Uso del token
- Carga de página:
- El sistema busca el token en la cookie o en el parámetro GET
- Token validado (no expirado, existe en la base de datos)
- Sesión validada (el ID del donante coincide)
- Se concede acceso si todas las comprobaciones son correctas
- Solicitudes AJAX:
- Token validado en cada solicitud
- El ID del donante del token debe coincidir con el ID del donante solicitado
- El ID del donante de la sesión debe coincidir con el ID del donante del token
Expiración del Token
- Tiempo de expiración: Configurable (predeterminado: 2 horas)
- Comprobación de expiración: Basado en la marca de tiempo de
magic_link_verify_throttle - Comportamiento del token expirado:
- El token ya no es válido
- El usuario debe solicitar un nuevo enlace mágico
- Mensaje de error mostrado
Invalidación de Token
Los tokens se invalidan en los siguientes escenarios:
- Nueva solicitud de enlace mágico: Todos los tokens existentes para el donante se invalidan cuando se solicita un nuevo enlace mágico
- Cierre de sesión del usuario: Todos los tokens del donante se invalidan al cerrar sesión
- Expiración del token: Los tokens expirados se invalidan automáticamente
- Desajuste de sesión: Si el ID del donante de la sesión y el token no coinciden, la sesión se borra
Proceso de cierre de sesión
- Solicitud de cierre de sesión:
- El usuario hace clic en el enlace de cierre de sesión (requiere nonce)
- Nonce verificado
- ID del donante recuperado de la sesión
- Invalidación de token:
- Todos los tokens del donante se borran de la base de datos
- Datos de sesión borrados
- Cookies borradas
- Redirección:
- El usuario es redirigido a la página de inicio (URL limpia, sin parámetros de consulta)
- La URL de redirección se puede filtrar a través de
charitable_magic_link_logout_redirect
Notas adicionales
Compatibilidad
- El enlace mágico funciona junto con la autenticación de usuario estándar de WordPress
- Si un usuario ha iniciado sesión, se omite el enlace mágico
- El enlace mágico solo se activa para usuarios que no han iniciado sesión
Registro
El sistema registra las actividades de los enlaces mágicos en el registro de donantes:
magic_link_sent– Cuando se envía un correo electrónico de enlace mágicomagic_link_used– Cuando se utiliza con éxito un enlace mágico para acceder al panelmagic_link_failed– Cuando un intento de enlace mágico falla (token no válido/caducado)
Modo de depuración
Cuando WP_DEBUG está habilitado, hay disponible un registro detallado para:
- Validación de tokens
- Gestión de sesiones
- Limitación de velocidad
- Procesamiento de cierre de sesión
Recursos adicionales
Para obtener más información sobre cómo extender la funcionalidad de los enlaces mágicos:
- Documentación para desarrolladores de Charitable
- Documentación de ganchos y filtros de WordPress
- Repositorio de GitHub de Charitable
Versión del documento: 1.0
Última actualización: noviembre de 2025
