Documentazione · Documentazione tecnica

Archiviazione di opzioni e impostazioni

Questo documento descrive come il plugin ADP Car Market Hub memorizza le sue impostazioni: quali chiavi vengono utilizzate, dove risiedono nel database e come i valori vengono letti e scritti dal plugin.

Quando utilizzare questo documento

Leggere questo documento se si ha la necessità di:

Individuare una specifica impostazione del plugin in wp_options.
Capire quale opzione gestisce un particolare interruttore di funzionalità.
Pianificare un backup, una migrazione di ambiente o un deployment da staging a produzione che includa le impostazioni del plugin.
Creare un'integrazione personalizzata che legga un'opzione del plugin dall'esterno del codice del plugin stesso.

Per le tabelle e le entità sottostanti, consultare lo Schema del database e il Modello dei dati.

Panoramica

Tutte le impostazioni configurabili dall'utente sono memorizzate come opzioni standard di WordPress nella tabella wp_options. Il plugin non mantiene una tabella delle impostazioni separata.

Le chiavi delle opzioni sono definite come costanti nella classe AS24CI\Options in modo che:

Le chiavi esistano in un solo punto del codice sorgente.
La routine di disinstallazione possa derivare automaticamente l'elenco completo delle opzioni da AS24CI\Options::get_all_keys().
Il codice che legge o scrive un'impostazione possa fare riferimento alla costante invece di ripetere la stringa non elaborata.

La maggior parte delle impostazioni sono scalari (stringa, intero, booleano codificato come 0/1). Alcune sono array (ad esempio Seller ID, sovrascritture di mappatura, zone di layout, network di condivisione social). Gli array vengono memorizzati utilizzando la serializzazione predefinita delle opzioni di WordPress.

Convenzioni di denominazione

Tutte le chiavi delle opzioni del plugin iniziano con il prefisso as24ci_. I prefissi dei sottosistemi raggruppano le impostazioni correlate:

as24ci_design_*, as24ci_archive_*, as24ci_single_*, as24ci_fav_*, as24ci_comp_* — impostazioni di design e tipografia.
as24ci_cron_*, as24ci_image_queue* — pianificatore e coda delle immagini.
as24ci_lead_* — modulo di contatto, consenso e modelli di email.
as24ci_ai_* — AI Assistant.
as24ci_analytics_* — analytics e consenso.
as24ci_test_drive_* — prenotazione test-drive.
as24ci_envkv_* — configurazione dei costi di gestione tedeschi EnVKV / WLTP.
as24ci_lm_*, as24ci_layout_* — zone del Layout Manager e layout dell'archivio.
as24ci_feature_* — interruttori di funzionalità per i sottosistemi opzionali.

L'inventario completo delle chiavi delle opzioni è l'elenco pubblico restituito da AS24CI\Options::get_all_keys().

Categorie di impostazioni

La classe Options definisce ben oltre cento costanti. L'elenco seguente le raggruppa per scopo. Laddove un valore predefinito è documentato nel codice (costante predefinita, add_option() in seed_safe_defaults(), o chiamate inline get_option(..., $default)), esso viene indicato. Verificare qualsiasi valore non predefinito rispetto alla versione corrente del plugin prima della pubblicazione.

API e autenticazione

Utilizzate da AS24CI\Client per comunicare con l'API di AutoScout24.

as24ci_base_url (Options::BASE_URL) — URL di base dell'API.
as24ci_token_url (Options::TOKEN_URL) — URL del token OAuth.
as24ci_seller_ids (Options::SELLER_IDS) — elenco separato da virgole di identificatori del venditore (Seller ID).
as24ci_client_id (Options::CLIENT_ID) — Client ID OAuth.
as24ci_client_secret (Options::CLIENT_SECRET) — Client secret OAuth.
as24ci_token_audience (Options::TOKEN_AUDIENCE) — parametro audience di OAuth.
as24ci_default_currency (Options::DEFAULT_CURRENCY) — codice valuta ISO 4217 predefinito (inserito come EUR all'attivazione).

Questi valori sono richiesti per il funzionamento di qualsiasi importazione e devono essere trattati come riservati. Non vengono mostrati ai non amministratori.

Comportamento dell'importatore

Utilizzato da AS24CI\Importer e AS24CI\Image_Importer.

as24ci_default_post_status (Options::DEFAULT_POST_STATUS) — stato assegnato ai veicoli appena importati. Inserito come draft in modo che gli amministratori possano verificare le mappature prima della pubblicazione.
as24ci_default_post_author (Options::DEFAULT_POST_AUTHOR) — ID utente autore predefinito.
as24ci_import_images (Options::IMPORT_IMAGES) — indica se importare le immagini.
as24ci_max_images (Options::MAX_IMAGES) — numero massimo di immagini per veicolo. Inserito come 30. Un valore pari a 0 viene trattato come nessun limite dall'importatore; l'importatore di immagini applica inoltre il limite in modo difensivo.
as24ci_convert_to_webp (Options::CONVERT_TO_WEBP) — converte le immagini importate in WebP.
as24ci_webp_quality (Options::WEBP_QUALITY) — qualità WebP (1–100; predefinita a 80 se non impostata).
as24ci_full_sync (Options::FULL_SYNC) — quando abilitato, i veicoli non più presenti nell'API vengono eliminati dopo ogni importazione. Inserito come 0.
as24ci_verbose_logging (Options::VERBOSE_LOGGING) — righe di log dettagliate per veicolo / per immagine.
as24ci_mapping_overrides (Options::MAPPING_OVERRIDES) — array di sovrascritture di etichette e visibilità per campo AS24.

Pianificatore e automazione

Utilizzato da AS24CI\Scheduler e AS24CI\Cron_Endpoint.

as24ci_auto_import_enabled (Options::AUTO_IMPORT_ENABLED).
as24ci_cron_schedule (Options::CRON_SCHEDULE) — uno tra hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom. Predefinito: hourly.
as24ci_cron_start_time (Options::CRON_START_TIME) — ora di inizio per le pianificazioni giornaliere / due volte al giorno in HH:MM (24 ore, fuso orario del sito WordPress). Predefinito: 06:00.
as24ci_cron_custom_minutes (Options::CRON_CUSTOM_MINUTES) — intervallo per la pianificazione personalizzata. Minimo: 15. Predefinito: 30.
as24ci_cron_mode (Options::CRON_MODE) — wp-cron o server-cron.
as24ci_cron_token (Options::CRON_TOKEN) — token per l'endpoint REST cron-import.
as24ci_cron_max_vehicles (Options::CRON_MAX_VEHICLES) — limite massimo di veicoli per esecuzione del cron. 0 = illimitato.
as24ci_cron_image_queue (Options::CRON_IMAGE_QUEUE) — abilita la modalità coda immagini durante le esecuzioni del cron. Predefinito: 1.
as24ci_image_queue (Options::IMAGE_QUEUE_DATA) — payload persistente della coda di immagini in attesa.
as24ci_image_queue_last_run (Options::IMAGE_QUEUE_LAST_RUN) — statistiche dell'ultima esecuzione del worker della coda immagini.
as24ci_last_run_time (Options::LAST_RUN_TIME) — timestamp Unix dell'ultima importazione completata.
as24ci_last_run_status (Options::LAST_RUN_STATUS) — array dei conteggi { inserted, updated, skipped, errors, sync_deleted }.
as24ci_last_external_cron_run (Options::LAST_EXTERNAL_CRON_RUN) — timestamp Unix dell'ultimo ping cron esterno riuscito.

Pagine predefinite e ciclo di vita

as24ci_create_default_pages (Options::CREATE_DEFAULT_PAGES) — indica se creare le pagine Cars / Compare / Favorites all'attivazione.
as24ci_page_archive_id, as24ci_page_compare_id, as24ci_page_favorites_id — ID delle pagine create all'attivazione.
as24ci_delete_data_on_uninstall (Options::DELETE_DATA_ON_UNINSTALL) — quando impostato su 1, la routine di disinstallazione elimina i veicoli, i lead, gli allegati importati e le pagine create all'attivazione.
as24ci_caps_version (Options::CAPS_VERSION) — marcatore di migrazione delle funzionalità (capability).
as24ci_db_version (Options::DB_VERSION) — marcatore di migrazione dei dati/schema.

Marcatori di schema per tabelle personalizzate

as24ci_vehicles_db_version — versione dello schema della tabella as24_vehicles.
as24ci_search_agent_db_version — versione dello schema della tabella as24ci_search_agents.
as24ci_content_studio_db_version — versione dello schema condivisa delle tabelle as24ci_content_studio_jobs e as24ci_content_studio_assets.
as24ci_analytics_db_version — versione dello schema della tabella as24ci_analytics (costante AS24CI\Analytics::DB_VERSION_KEY).

Interruttori delle funzionalità (Feature toggles)

Tutti gli interruttori delle funzionalità risiedono su AS24CI\Options::FEATURE_*. I valori predefiniti vengono inseriti da AS24CI\Plugin::seed_safe_defaults() all'attivazione:

Impostati come attivi per impostazione predefinita: FEATURE_SCHEMA, FEATURE_SOCIAL_SHARE, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, FEATURE_SITEMAP, FEATURE_DASHBOARD_WIDGET, FEATURE_LAZY_LOADING, FEATURE_BULK_ACTIONS, FEATURE_EXPORT, FINANCING_ENABLED, LAYOUT_MANAGER_ENABLED. FEATURE_SEARCH_AGENT non ha un valore predefinito esplicito inserito, ma il suo controllo al momento della registrazione tratta qualsiasi valore diverso da '0' come abilitato, quindi è effettivamente attivo fin da subito.
Impostati come disattivi per impostazione predefinita per motivi di sicurezza/conformità: ANALYTICS_ENABLED, REST_API_ENABLED, AI_ASSISTANT_ENABLED, TEST_DRIVE_ENABLED.

L'elenco completo degli interruttori e la loro semantica sono documentati nel blocco di documentazione della classe per ciascuna costante.

Modulo di contatto (Lead) ed email

Utilizzato da AS24CI\Contact_Form e AS24CI\Leads_CPT.

as24ci_lead_recipient_email — sovrascrittura dell'email del destinatario.
as24ci_lead_field_* (nome/email/telefono/messaggio) — mostra/nasconde i campi del modulo. Valore predefinito: 1.
as24ci_lead_consent_enabled, as24ci_lead_consent_text, as24ci_lead_privacy_url — configurazione della casella di controllo del consenso.
as24ci_lead_msg_success, as24ci_lead_msg_error — messaggi utente personalizzati.
as24ci_lead_email_subject_dealer, as24ci_lead_email_subject_customer, as24ci_lead_email_template_dealer, as24ci_lead_email_template_customer — modelli di email con supporto per i segnaposto.

Analytics

as24ci_analytics_enabled — interruttore principale. Predefinito: 0.
as24ci_analytics_retention_days — finestra di conservazione in giorni. Predefinito: 180.
as24ci_analytics_bi_enabled — tracciamento degli eventi BI / esteso.
as24ci_analytics_require_consent — quando impostato su 1, blocca il tracciamento fino a quando non arriva un segnale di consenso esterno tramite il filtro as24ci_analytics_consent_check.
as24ci_analytics_filter_minimization — rimuove i valori di ricerca a testo libero dai payload di analytics. Predefinito: 1.
as24ci_analytics_privacy_jurisdiction — auto, gdpr, dsgvo, revdsg, uk_gdpr o generic.

AI Assistant

as24ci_ai_assistant_enabled (Options::AI_ASSISTANT_ENABLED).
as24ci_ai_assistant_language, as24ci_ai_assistant_tone, as24ci_ai_assistant_max_length, as24ci_ai_assistant_custom_prompt.
as24ci_ai_assistant_auto_generate, as24ci_ai_gen_alt_text, as24ci_ai_gen_seo, as24ci_ai_extract_highlights.

Le funzionalità di intelligenza artificiale utilizzano una configurazione gestita di Google Gemini. Le costanti relative a chiave/modello Gemini scritte direttamente nel codice su AS24CI\Ai_Config sono state rimosse; Ai_Config è ora una facciata leggera (get_managed_gemini_api_key() / get_effective_model()) che recupera la chiave Gemini del cliente dalla credenziale crittografata sincronizzata dalla piattaforma API e gestita da AS24CI\Ai_Credential_Manager (il modello a runtime è sempre Ai_Credential_Manager::PRIMARY_MODEL). Non esiste alcuna opzione per provider, modello o chiave API in wp_options, e la chiave non viene mai mostrata nell'interfaccia di amministrazione; il provisioning dell'IA per il cliente viene completato server-to-server da AD Promotion dopo l'installazione.

Prenotazione test drive

Utilizzato da AS24CI\Test_Drive.

as24ci_test_drive_enabled — interruttore principale. Predefinito: 0.
as24ci_test_drive_available_days — array di numeri dei giorni ISO (1=Lun … 7=Dom).
as24ci_test_drive_start_time, as24ci_test_drive_end_time — finestra temporale (HH:MM, 24 ore). Valori predefiniti: 08:00 / 18:00.
as24ci_test_drive_slot_duration — durata dello slot in minuti. Predefinito: 30.
as24ci_test_drive_blackout_dates — array di stringhe Y-m-d.

Webhook, REST API e servizi esterni

as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import, as24ci_webhook_secret.
as24ci_rest_api_enabled (Options::REST_API_ENABLED).
as24ci_hub_api_key, as24ci_hub_target_market — integrazione Market Hub (mercato di destinazione predefinito: DE).
as24ci_locations — array delle sedi della concessionaria (autoload disattivato; caricato solo sulle pagine dei singoli veicoli e nella scheda di amministrazione Locations).

Licenze e accesso gestito

Utilizzato da AS24CI\License_Manager. Questi elementi contengono lo stato della licenza della piattaforma API di ADP Car Market Hub e i diritti sulle funzionalità:

as24ci_license_plan, as24ci_license_status, as24ci_license_last_error, as24ci_license_support_until, as24ci_license_expires_at, as24ci_license_installation_uid, as24ci_license_normalized_domain (costanti Options::LICENSE_*).
Lo stato dei diritti sulle funzionalità regola i percorsi operativi (importazione/scrittura) e di IA; viene aggiornato dal cron giornaliero as24ci_license_refresh e dall'endpoint di ricezione del segnale di aggiornamento della licenza.

CMH Team

Utilizzato da AS24CI\Team (archiviazione basata su opzioni, che rispecchia Locations):

as24ci_team_members (Options::TEAM_MEMBERS) — array di contatti commerciali (non sono richiesti account utente WordPress).
as24ci_team_location_defaults, as24ci_team_standards, as24ci_team_rules — configurazione di supporto.

Content Studio

Le chiavi di Content Studio sono definite su AS24CI\Content_Studio_Options (non AS24CI\Options) e vengono aggiunte esplicitamente all'elenco di disinstallazione:

as24ci_content_studio_db_version — versione dello schema condivisa delle due tabelle Content Studio.
as24ci_content_studio_google_api_key, as24ci_content_studio_default_language, as24ci_content_studio_default_tone, as24ci_content_studio_brand_voice, as24ci_content_studio_disclaimer_text, as24ci_content_studio_compliance_notes.

Layout Manager e layout dell'archivio

as24ci_layout_manager_enabled — interruttore principale. Inserito come 1 (attivo) da seed_safe_defaults().
as24ci_lm_zone_* — array di layout per zona per filtri di ricerca, schede dell'archivio, pagina singola principale/barra laterale/fondo, confronto e preferiti.
as24ci_lm_block_<id> — configurazione dei campi per blocco.
as24ci_layout_archive_columns — 1–4. Predefinito: 3.
as24ci_archive_default_sort — date_desc, price_asc, price_desc o mileage_asc.
as24ci_archive_per_page — veicoli per pagina. Predefinito: 24.
as24ci_archive_list_excerpt_length — caratteri dell'estratto nella vista a elenco (0–500). Predefinito: 75.
as24ci_layout_search_filters, as24ci_layout_single_main, as24ci_layout_single_sidebar, as24ci_layout_single_bottom — array ordinati di chiavi di blocco con elenchi predefiniti documentati.

Design e tipografia

as24ci_design_* più le opzioni di tipografia specifiche per pagina as24ci_single_*, as24ci_archive_*, as24ci_fav_* e as24ci_comp_*. Gestiscono lo schema dei colori, i caratteri, i layout, i badge e le opzioni della galleria esposti nella scheda di amministrazione Design & Styles. L'elenco completo è enumerato sotto forma di costanti su AS24CI\Options.

EnVKV / WLTP

Per la conformità al mercato tedesco, utilizzato dal calcolatore dei costi di gestione EnVKV sulle pagine dei singoli veicoli.

as24ci_envkv_year — anno di riferimento (predefinito 2024).
as24ci_envkv_price_petrol, as24ci_envkv_price_diesel, as24ci_envkv_price_electric — prezzi del carburante/elettricità.
as24ci_envkv_co2_price_low, as24ci_envkv_co2_price_med, as24ci_envkv_co2_price_high — costo della CO₂ per tonnellata.
as24ci_envkv_show_costs_100km — mostra i costi di gestione (predefinito no).

Istruzioni passo dopo passo

L'interfaccia utente delle impostazioni del plugin è il modo supportato per modificare le opzioni. I punti seguenti descrivono il ciclo di vita supportato.

Prima configurazione. All'attivazione, seed_safe_defaults() scrive un set conservativo di valori predefiniti utilizzando add_option(). I valori esistenti non vengono mai sovrascritti. Aprire la scheda di amministrazione pertinente per verificare i valori predefiniti prima della messa online.
Modifiche quotidiane. Modificare le impostazioni nella scheda di amministrazione corrispondente (Importer, Automation, Design & Styles, Mapping, AI Assistant, ecc.). Le modifiche vengono salvate tramite la Settings API di WordPress.
Backup. I backup standard del database di WordPress acquisiscono tutte le opzioni del plugin poiché risiedono in wp_options. Non è richiesto alcun backup aggiuntivo.
Migrazioni di ambiente. Quando si sposta un sito tra ambienti, copiare le righe as24ci_* pertinenti insieme al resto di wp_options. Trattare as24ci_client_id, as24ci_client_secret, as24ci_cron_token e il segreto del webhook (as24ci_webhook_secret) come riservati. Si noti che sulle installazioni migrate alla versione dati 5 questi segreti reversibili sono memorizzati con crittografia AES-256-GCM e il token cron è memorizzato tramite hash (vedere il passaggio di migrazione 5 in Plugin Bootstrap And Lifecycle). La chiave Gemini gestita non è memorizzata in wp_options; viene sincronizzata server-to-server dalla piattaforma API (mantenuta crittografata da AS24CI\Ai_Credential_Manager) e non viene migrata tramite i trasferimenti di database.
Ripristino di un'impostazione. Eliminare l'opzione (o utilizzare il pulsante di ripristino della scheda di amministrazione, ove fornito). Il plugin utilizzerà come fallback il valore predefinito documentato per tale impostazione.

Riferimento per la configurazione

Utilizzare AS24CI\Options::get_all_keys() (restituito dalla riflessione sulla classe) per l'elenco autorevole e completo delle chiavi delle opzioni per qualsiasi versione del plugin. L'elenco sopra è raggruppato per riferimento; le nuove costanti aggiunte a Options vengono incluse automaticamente nella pulizia durante la disinstallazione.

Note operative

Tutte le letture delle opzioni nel codice del plugin passano attraverso get_option() con un valore predefinito documentato, in modo che le righe mancanti si comportino allo stesso modo dei valori predefiniti di una nuova installazione.
Un piccolo numero di opzioni è intenzionalmente autoload = false per mantenere ridotta la tabella delle opzioni caricate automaticamente (autoload). Esempi degni di nota includono as24ci_image_queue, as24ci_image_queue_last_run e as24ci_locations.
seed_safe_defaults() viene eseguito nuovamente come parte della fase di migrazione 4 in modo che le installazioni esistenti ricevano eventuali nuovi valori predefiniti sicuri senza sovrascrivere i valori modificati dall'amministratore.
Le installazioni multisito memorizzano le opzioni per singolo sito. La routine di disinstallazione itera su ciascun sito tramite switch_to_blog().

Risoluzione dei problemi

Un'impostazione viene ripristinata dopo l'aggiornamento. Il plugin non sovrascrive mai i valori delle opzioni esistenti durante gli aggiornamenti. Verificare che la modifica sia stata salvata (la riga dell'opzione esiste in wp_options) e che nessuno strumento di gestione della configurazione stia ripristinando un valore precedente.
Le modifiche alla pianificazione di Cron vengono ignorate. L'utilità di pianificazione pianifica nuovamente WP-Cron solo quando viene chiamato il suo metodo reschedule(). Utilizzare la scheda Importazione e limiti per salvare la nuova pianificazione anziché modificare direttamente l'opzione.
Una migrazione reimposta inaspettatamente un'opzione. Solo il valore di ANALYTICS_REQUIRE_CONSENT viene intenzionalmente normalizzato dalla fase di migrazione 2 (forzato a 0). Tutte le altre impostazioni vengono preservate dalle fasi di migrazione.
Dati caricati automaticamente obsoleti o di grandi dimensioni. Ispezionare la dimensione delle opzioni caricate automaticamente in wp_options e disabilitare l'autoload per qualsiasi opzione personalizzata del plugin che si potrebbe aver aggiunto e che memorizza array di grandi dimensioni.