Notas técnicas de las alertas de búsqueda

Este documento describe la característica Search Agent / Smart Stock Alerts (Agente de búsqueda / Alertas de stock inteligente): cómo se suscriben los visitantes a las búsquedas guardadas, cómo funciona el flujo de doble opt-in (confirmación en dos pasos), dónde se almacenan las suscripciones y cómo se activa el motor de coincidencia después de cada importación.

Cuándo usar este documento

Lea este documento si necesita:

• Diagnosticar correos electrónicos de confirmación de suscripción duplicados o no recibidos.
• Comprender cómo se realiza la coincidencia y qué criterios son compatibles.
• Planificar una copia de seguridad o migración de la base de datos que incluya la tabla de suscripciones.
• Auditar el comportamiento de privacidad y retención de datos en torno a las búsquedas guardadas.

Descripción general

La característica está implementada en AS24CI\Search_Agent y:

1. Renderiza un formulario de suscripción (normalmente dentro de la zona de filtros de búsqueda) que envía un POST a la acción AJAX as24ci_search_agent_subscribe.
2. Valida el correo electrónico y los criterios seleccionados, genera un token de confirmación de 64 caracteres y almacena una fila con estado pending (pendiente).
3. Envía un correo electrónico de confirmación que contiene un enlace de un solo clic con el token. Al hacer clic en el enlace se activa la suscripción.
4. En cada importación de vehículos exitosa, evalúa cada suscripción active (activa) frente al nuevo vehículo y envía un correo electrónico de notificación cuando los criterios coinciden.
5. Proporciona enlaces para darse de baja con un solo clic en cada correo electrónico de notificación.

Un campo trampa para bots (honeypot) (as24ci_hp_field) descarta silenciosamente los envíos obvios de bots mientras devuelve una respuesta de éxito para que no se proporcione información de diagnóstico a los bots.

Tabla de la base de datos

Las suscripciones se almacenan en <prefix>as24ci_search_agents:

Índices: (status), (token). La versión del esquema se almacena en la opción as24ci_search_agent_db_version y dbDelta() se aplica según sea necesario.

Criterios compatibles

Search_Agent::sanitize_criteria() acepta únicamente esta lista blanca de claves; todos los demás campos enviados con el formulario se descartan:

• make
• model
• body_type
• drive_type
• condition
• color
• min_price
• max_price
• mileage_max
• status

Los valores vacíos y la cadena literal all se tratan como "sin restricción" y se eliminan de los criterios almacenados para que el motor de coincidencia no filtre en exceso.

Al menos un criterio debe permanecer después del saneamiento; de lo contrario, el endpoint AJAX responde con HTTP 422 y un mensaje de error.

Paso a paso: flujo de suscripción

1. El visitante selecciona los criterios en el filtro de búsqueda y envía su correo electrónico al formulario del agente de búsqueda.
2. El frontend realiza un POST a as24ci_search_agent_subscribe con el nonce as24ci_search_agent. Los nonces fallidos devuelven HTTP 403.
3. El plugin valida el correo electrónico y los criterios, genera un token, inserta una fila pending y envía el correo electrónico de confirmación.
4. El visitante hace clic en el enlace (?as24ci_sa_action=confirm&token=<token>). El controlador init verifica la longitud del token (debe ser de 64 caracteres), actualiza la fila a active y establece confirmed_at.
5. Tras una confirmación exitosa, el visitante es redirigido a la URL de inicio con ?as24ci_sa_msg=confirmed. El flujo para darse de baja utiliza el mismo mecanismo de redirección con unsubscribed.

Paso a paso: flujo de coincidencia

1. El importador activa as24ci_vehicle_imported después de cada creación o actualización.
2. Search_Agent::on_vehicle_imported() se ejecuta con prioridad 20.
3. Se omiten las actualizaciones: solo los vehículos recién creados activan las notificaciones, para evitar enviar spam a los suscriptores cuando cambia un vehículo existente.
4. Se cargan las suscripciones activas y se evalúan sus criterios frente a los términos y metadatos del post (post meta) del vehículo.
5. Cada coincidencia da como resultado un correo electrónico de notificación enviado a través de wp_mail() que contiene el título del vehículo, el enlace, el resumen de los criterios y la URL para darse de baja.

Referencia de configuración

La propia característica de Agente de búsqueda se activa o desactiva mediante el interruptor de características del plugin as24ci_feature_search_agent. Las plantillas de correo electrónico utilizan texto plano y son traducibles. El formato del token es fijo (64 caracteres hexadecimales de random_bytes(32)).

Para obtener la lista completa de opciones del plugin, consulte Options And Settings Storage.

Notas operativas

• El endpoint es público (se registra wp_ajax_nopriv_*) para que los visitantes anónimos puedan suscribirse. La autenticación se basa en el nonce de AJAX y el honeypot.
• Los tokens son criptográficamente aleatorios y se almacenan como texto hexadecimal plano. Trate la tabla como contenedora de datos personales: nombre, correo electrónico y los criterios de búsqueda almacenados del visitante.
• Las actualizaciones no activan notificaciones. Las reimportaciones de anuncios existentes (bajada de precio, actualización de kilometraje, etc.) son intencionadamente silenciosas. Verifique esto con la versión actual del plugin si planea cambiar este comportamiento.
• La columna frequency se incluye en el esquema para uso futuro; el motor de coincidencia actual envía las notificaciones de inmediato con cada nueva coincidencia.
• Los endpoints de confirmación y cancelación de suscripción se enrutan a través de parámetros de consulta ?as24ci_sa_action=... en la URL de inicio; no se introducen reglas de reescritura personalizadas.
• La tabla se elimina al desinstalar (independientemente del interruptor eliminar datos al desinstalar) porque contiene datos personales. Consulte Uninstall And Cleanup Behavior.

Resolución de problemas

• No se recibe el correo de confirmación: compruebe las carpetas de correo no deseado (spam); luego verifique la configuración de SMTP/servidor de correo. El plugin utiliza wp_mail() para todos los mensajes de suscripción.
• El enlace de confirmación no informa de nada: el token estaba vacío, no tenía exactamente 64 caracteres o la fila ya estaba confirmada. El endpoint finaliza silenciosamente si el token tiene un formato incorrecto; esto evita ataques de enumeración.
• El suscriptor no recibe notificaciones incluso después de una importación coincidente: confirme que el vehículo fue una nueva inserción (las actualizaciones no notifican), que la suscripción está marcada como active y que al menos un criterio es lo suficientemente restrictivo como para mapearse con una clave meta o término de taxonomía conocido.
• Muchas notificaciones duplicadas durante una reimportación: no debería ocurrir porque las actualizaciones se filtran, pero una reimportación completa que recree las publicaciones desde cero sí activaría las notificaciones. Programe las reimportaciones completas durante las horas de menor actividad y considere desactivar temporalmente el interruptor del Agente de búsqueda.
• La suscripción por AJAX siempre devuelve éxito incluso con datos incorrectos: se activó el campo honeypot. Confirme que el formulario no rellenó inadvertidamente la entrada oculta as24ci_hp_field.

Documentos relacionados

• AJAX Actions
• Cron Events And Scheduler
• Options And Settings Storage
• Security And Capabilities
• Uninstall And Cleanup Behavior
• Import Engine