Note tecniche sugli avvisi di ricerca

Questo documento descrive la funzionalità Search Agent / Smart Stock Alerts: come i visitatori si iscrivono alle ricerche salvate, come funziona il flusso di double-opt-in, dove vengono memorizzate le iscrizioni e come viene attivato il motore di corrispondenza dopo ogni importazione.

Quando utilizzare questo documento

Leggi questo documento se hai bisogno di:

• Diagnosticare email di conferma dell'iscrizione mancanti o duplicate.
• Comprendere come viene eseguita la corrispondenza e quali criteri sono supportati.
• Pianificare un backup o una migrazione del database che includa la tabella delle iscrizioni.
• Verificare il comportamento in materia di privacy e conservazione dei dati relativo alle ricerche salvate.

Panoramica

La funzionalità è implementata in AS24CI\Search_Agent e:

1. Mostra un modulo di iscrizione (in genere all'interno della zona dei filtri di ricerca) che invia una richiesta POST all'azione AJAX as24ci_search_agent_subscribe.
2. Valida l'email e i criteri selezionati, genera un token di conferma di 64 caratteri e memorizza una riga con stato pending (in attesa).
3. Invia un'email di conferma contenente un link con un clic che include il token. Facendo clic sul link si attiva l'iscrizione.
4. Ad ogni importazione di veicoli andata a buon fine, valuta ciascuna iscrizione active (attiva) rispetto al nuovo veicolo e invia un'email di notifica quando i criteri corrispondono.
5. Fornisce link di disiscrizione con un clic in ogni email di notifica.

Un campo honeypot per i bot (as24ci_hp_field) scarta silenziosamente gli invii palesi dei bot restituendo comunque una risposta di successo, in modo da non fornire informazioni diagnostiche ai bot.

Tabella del database

Le iscrizioni sono memorizzate in <prefix>as24ci_search_agents:

Indici: (status), (token). La versione dello schema è memorizzata nell'opzione as24ci_search_agent_db_version e dbDelta() viene applicato secondo necessità.

Criteri supportati

Search_Agent::sanitize_criteria() accetta solo questa whitelist di chiavi; tutti gli altri campi inviati con il modulo vengono scartati:

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

I valori vuoti e la stringa letterale all sono trattati come "nessun vincolo" e rimossi dai criteri memorizzati in modo che il motore di corrispondenza non filtri eccessivamente.

Almeno un criterio deve rimanere dopo l'igienizzazione; in caso contrario, l'endpoint AJAX risponde con HTTP 422 e un messaggio di errore.

Passo dopo passo: flusso di iscrizione

1. Il visitatore seleziona i criteri nel filtro di ricerca e invia la propria email al modulo del search-agent.
2. Il front-end invia una richiesta POST a as24ci_search_agent_subscribe con il nonce as24ci_search_agent. I nonce non validi restituiscono HTTP 403.
3. Il plugin valida l'email e i criteri, genera un token, inserisce una riga pending e invia l'email di conferma.
4. Il visitatore fa clic sul link (?as24ci_sa_action=confirm&token=<token>). Il gestore init verifica la lunghezza del token (deve essere di 64 caratteri), aggiorna la riga impostandola su active e imposta confirmed_at.
5. In caso di conferma andata a buon fine, il visitatore viene reindirizzato all'URL home con ?as24ci_sa_msg=confirmed. Il flusso di disiscrizione utilizza lo stesso meccanismo di reindirizzamento con unsubscribed.

Passo dopo passo: flusso di corrispondenza

1. L'importatore attiva as24ci_vehicle_imported dopo ogni creazione o aggiornamento.
2. Search_Agent::on_vehicle_imported() viene eseguito con priorità 20.
3. Gli aggiornamenti vengono saltati — solo i veicoli appena creati attivano le notifiche, per evitare di inviare spam agli iscritti quando un veicolo esistente subisce modifiche.
4. Le iscrizioni attive vengono caricate e i loro criteri vengono valutati rispetto ai termini del veicolo e ai post meta.
5. Ogni corrispondenza genera un'email di notifica inviata tramite wp_mail() contenente il titolo del veicolo, il link, il riepilogo dei criteri e l'URL di disiscrizione.

Riferimento di configurazione

La funzionalità Search Agent stessa viene abilitata o disabilitata tramite l'interruttore delle funzionalità del plugin as24ci_feature_search_agent. I modelli di email utilizzano testo normale e sono traducibili. Il formato del token è fisso (64 caratteri esadecimali da random_bytes(32)).

Per l'elenco completo delle opzioni del plugin, consulta Opzioni e memorizzazione delle impostazioni.

Note operative

• L'endpoint è pubblico (è registrato wp_ajax_nopriv_*) in modo che i visitatori anonimi possano iscriversi. L'autenticazione si basa sul nonce AJAX e sull'honeypot.
• I token sono crittograficamente casuali e memorizzati come testo esadecimale normale. Tratta la tabella come contenente dati personali: nome, email e criteri di ricerca memorizzati del visitatore.
• Gli aggiornamenti non attivano notifiche. Le reimportazioni di annunci esistenti (calo di prezzo, aggiornamento del chilometraggio, ecc.) sono intenzionalmente silenziose. Verifica rispetto alla versione corrente del plugin se intendi modificare questo comportamento.
• La colonna frequency è inclusa nello schema per un uso futuro; l'attuale motore di corrispondenza invia le notifiche immediatamente su ogni nuova corrispondenza.
• Gli endpoint di conferma e disiscrizione sono instradati tramite i parametri di query ?as24ci_sa_action=... sull'URL home — non vengono introdotte regole di riscrittura personalizzate.
• La tabella viene eliminata al momento della disinstallazione (indipendentemente dall'interruttore elimina i dati alla disinstallazione) perché contiene dati personali. Vedi Comportamento di disinstallazione e pulizia.

Risoluzione dei problemi

• Nessuna email di conferma ricevuta — controlla le cartelle dello spam; quindi verifica la configurazione di SMTP/mailer. Il plugin utilizza wp_mail() per tutti i messaggi di iscrizione.
• Il link di conferma non segnala nulla — il token era vuoto o non era esattamente di 64 caratteri, oppure la riga era già stata confermata. L'endpoint esce silenziosamente se il token è malformato; questo previene gli attacchi di enumerazione.
• L'iscritto non riceve notifiche anche dopo un'importazione corrispondente — conferma che il veicolo sia stato un nuovo inserimento (gli aggiornamenti non inviano notifiche), che l'iscrizione sia active e che almeno un criterio sia sufficientemente restrittivo da mappare su una chiave meta o un termine di tassonomia noti.
• Molte notifiche duplicate durante una reimportazione — non dovrebbe verificarsi perché gli aggiornamenti vengono filtrati, ma una *reimportazione completa* che ricrea i post da zero attiverebbe le notifiche. Pianifica le reimportazioni complete durante le ore di minore attività e valuta la possibilità di disabilitare temporaneamente l'interruttore del Search Agent.
• L'iscrizione AJAX restituisce sempre successo anche con dati errati — il campo honeypot è stato attivato. Verifica che il modulo non abbia compilato inavvertitamente l'input nascosto as24ci_hp_field.

Documenti correlati

• Azioni AJAX
• Eventi Cron e pianificatore
• Opzioni e memorizzazione delle impostazioni
• Sicurezza e funzionalità
• Comportamento di disinstallazione e pulizia
• Motore di importazione